sinonym 0.2.4__tar.gz → 0.2.5__tar.gz

{sinonym-0.2.4 → sinonym-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sinonym
-Version: 0.2.4
+Version: 0.2.5
 Summary: Chinese Name Detection and Normalization Module
 Project-URL: Homepage, https://github.com/allenai/sinonym
 Project-URL: Repository, https://github.com/allenai/sinonym

{sinonym-0.2.4 → sinonym-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sinonym"
-version = "0.2.4"
+version = "0.2.5"
 description = "Chinese Name Detection and Normalization Module"
 readme = "README.md"
 requires-python = ">=3.10"

{sinonym-0.2.4 → sinonym-0.2.5}/scripts/README.md

@@ -5,7 +5,7 @@ Utility scripts for benchmarking, profiling, testing, and model training.
 ## Active Scripts
 
 ### `check_test_status.py`
-Runs the full test suite and reports individual test case failures with detailed diagnostics. Runs performance tests separately, then exits 0/1 based on whether the failure count matches the expected baseline (`EXPECTED_FAILURES = 52`). Improvements (fewer failures) also pass; regressions fail.
+Runs the full test suite and reports individual test case failures with detailed diagnostics. Runs performance tests separately, then exits 0/1 based on whether the failure count matches the expected baseline configured in `scripts/check_test_status.py`. Improvements (fewer failures) also pass; regressions fail.
 
 ```bash
 uv run python scripts/check_test_status.py

{sinonym-0.2.4 → sinonym-0.2.5}/sinonym/detector.py

@@ -178,6 +178,7 @@ from sinonym.services import (
     NameFormattingService,
     NameParsingService,
     NormalizationService,
+    NormalizedInput,
     ParseResult,
     PinyinCacheService,
     ServiceContext,
@@ -244,6 +245,114 @@ class ChineseNameDetector:
             # Initialize services
             self._initialize_services()
 
+    def _is_surname_group(self, tokens: list[str], normalized_cache: dict[str, str]) -> bool:
+        """Return whether a romanized Han token group is a surname component."""
+        if len(tokens) == 1:
+            token = tokens[0]
+            normalized = self._normalizer.get_normalized(token, normalized_cache)
+            return self._data.is_surname(token, normalized)
+
+        normalized_tokens = [self._normalizer.get_normalized(token, normalized_cache) for token in tokens]
+        spaced = " ".join(normalized_tokens)
+        compact = "".join(normalized_tokens)
+
+        return (
+            spaced in self._data.compound_surnames
+            or spaced in self._data.compound_surnames_normalized
+            or compact in self._data.compound_original_format_map
+        )
+
+    def _is_compound_surname_group(self, tokens: list[str], normalized_cache: dict[str, str]) -> bool:
+        """Return whether a romanized Han token group is a compound surname."""
+        return len(tokens) > 1 and self._is_surname_group(tokens, normalized_cache)
+
+    def _has_only_cjk_token_groups(self, normalized_input: NormalizedInput) -> bool:
+        """Return whether separator-delimited input tokens are all CJK characters."""
+        return len(normalized_input.tokens) > 1 and all(
+            token and all(self._config.cjk_pattern.search(char) for char in token)
+            for token in normalized_input.tokens
+        )
+
+    def _format_parse_result(
+        self,
+        surname_tokens: list[str],
+        given_tokens: list[str],
+        normalized_input: NormalizedInput,
+        original_order: list[str],
+    ) -> ParseResult:
+        """Format parsed components and attach stable structured name fields."""
+        formatted_name, given_final, surname_final, surname_str, given_str, middle_tokens = (
+            self._formatting_service.format_name_output_with_tokens(
+                surname_tokens,
+                given_tokens,
+                normalized_input.norm_map,
+                normalized_input.compound_metadata,
+            )
+        )
+        parsed = ParsedName(
+            surname=surname_str,
+            given_name=given_str,
+            surname_tokens=surname_final,
+            given_tokens=given_final,
+            middle_name=" ".join(middle_tokens) if middle_tokens else "",
+            middle_tokens=middle_tokens,
+            order=["given", "middle", "surname"],
+        )
+        parsed_original_order = ParsedName(
+            surname=surname_str,
+            given_name=given_str,
+            surname_tokens=surname_final,
+            given_tokens=given_final,
+            middle_name=" ".join(middle_tokens) if middle_tokens else "",
+            middle_tokens=middle_tokens,
+            order=original_order,
+        )
+        return ParseResult.success_with_name(
+            formatted_name,
+            parsed=parsed,
+            parsed_original_order=parsed_original_order,
+        )
+
+    def _normalize_spaced_all_chinese_name(self, normalized_input: NormalizedInput) -> ParseResult | None:
+        """Parse all-Han names whose whitespace already separates name components."""
+        if (
+            len(normalized_input.tokens) != self._config.min_tokens_required
+            or len(normalized_input.roman_tokens) <= self._config.min_tokens_required
+        ):
+            return None
+
+        first_group = self._cache_service.han_to_pinyin_fast(normalized_input.tokens[0])
+        last_group = self._cache_service.han_to_pinyin_fast(normalized_input.tokens[1])
+        if not first_group or not last_group:
+            return None
+
+        # OCR/noisy spacing can split a compound surname across the group boundary.
+        boundary_compound = first_group + last_group[:1] if len(first_group) == 1 and len(last_group) > 1 else []
+        if boundary_compound and self._is_surname_group(boundary_compound, normalized_input.norm_map):
+            surname_tokens = boundary_compound
+            given_tokens = last_group[1:]
+            original_order = ["surname", "given"]
+        else:
+            first_is_surname = self._is_surname_group(first_group, normalized_input.norm_map)
+            last_is_surname = self._is_surname_group(last_group, normalized_input.norm_map)
+            last_is_compound_surname = self._is_compound_surname_group(last_group, normalized_input.norm_map)
+
+            if last_is_surname and (not first_is_surname or last_is_compound_surname):
+                surname_tokens = last_group
+                given_tokens = first_group
+                original_order = ["given", "surname"]
+            elif first_is_surname:
+                surname_tokens = first_group
+                given_tokens = last_group
+                original_order = ["surname", "given"]
+            else:
+                return None
+
+        try:
+            return self._format_parse_result(surname_tokens, given_tokens, normalized_input, original_order)
+        except ValueError as e:
+            return ParseResult.failure(str(e))
+
     # Public API methods
     def get_cache_info(self) -> CacheInfo:
         """Get cache information."""
@@ -291,6 +400,11 @@ class ChineseNameDetector:
 
         # Try parsing in both orders - for all-Chinese inputs, choose best scoring parse
 
+        if self._has_only_cjk_token_groups(normalized_input):
+            grouped_result = self._normalize_spaced_all_chinese_name(normalized_input)
+            if grouped_result is not None:
+                return grouped_result
+
         if is_all_chinese and len(normalized_input.roman_tokens) == self._config.min_tokens_required:
             # For all-Chinese 2-token inputs, ALWAYS assume surname-first order
             # Two-character Chinese names are always (surname, given_name)
@@ -443,8 +557,8 @@ class ChineseNameDetector:
                     given_tokens,
                     original_tokens,
                     normalized_input.norm_map,
-                    False,
-                    original_compound_surname,
+                    is_all_chinese=False,
+                    original_compound_format=original_compound_surname,
                 )
                 used_original = order_tokens == original_tokens
 

{sinonym-0.2.4 → sinonym-0.2.5}/sinonym/services/batch_analysis.py

@@ -8,6 +8,7 @@ improve parsing accuracy for ambiguous individual names.
 
 from __future__ import annotations
 
+from statistics import median
 from typing import TYPE_CHECKING
 
 from sinonym.coretypes import (
@@ -20,6 +21,12 @@ from sinonym.coretypes import (
 )
 from sinonym.coretypes.results import ParsedName
 
+GUARDED_GIVEN_FIRST_BATCH_MIN_SHARE = 0.75
+GIVEN_NAME_SHAPE_MIN_SHARE = 0.5
+ULTRA_LOW_FIRST_SURNAME_MEDIAN_MAX = 130.0
+LONG_GIVEN_NAME_TOKEN_MIN_LENGTH = 6
+TWO_TOKEN_NAME_LENGTH = 2
+
 if TYPE_CHECKING:
     from sinonym.services.ethnicity import EthnicityClassificationService
     from sinonym.services.parsing import NameParsingService
@@ -69,10 +76,15 @@ class BatchAnalysisService:
             # Normalize once and reuse
             normalized_input = normalizer.apply(name)
             candidates, best_candidate = self._analyze_individual_name_with_normalized(
-                name, normalized_input, data,
+                name,
+                normalized_input,
+                data,
+                allow_guarded_given_first_bonus=False,
             )
             name_candidates.append((name, candidates, best_candidate, normalized_input.compound_metadata))
 
+        name_candidates = self._promote_guarded_given_first_batch_votes(name_candidates, normalizer, data)
+
         # Phase 2: Detect the dominant format pattern
         format_pattern = self._detect_format_pattern(name_candidates)
 
@@ -119,10 +131,15 @@ class BatchAnalysisService:
             # Normalize once for format detection (compound_metadata not needed)
             normalized_input = normalizer.apply(name)
             candidates, best_candidate = self._analyze_individual_name_with_normalized(
-                name, normalized_input, data,
+                name,
+                normalized_input,
+                data,
+                allow_guarded_given_first_bonus=False,
             )
             name_candidates.append((name, candidates, best_candidate, None))  # No compound_metadata needed for format detection
 
+        name_candidates = self._promote_guarded_given_first_batch_votes(name_candidates, normalizer, data)
+
         return self._detect_format_pattern(name_candidates)
 
     def _process_individually(self, names: list[str], normalizer, data, formatting_service) -> BatchParseResult:
@@ -181,7 +198,12 @@ class BatchAnalysisService:
         )
 
     def _analyze_individual_name_with_normalized(
-        self, name: str, normalized_input, _data,
+        self,
+        name: str,
+        normalized_input,
+        _data,
+        *,
+        allow_guarded_given_first_bonus: bool = True,
     ) -> tuple[list[ParseCandidate], ParseCandidate | None]:
         """Analyze a single name using pre-computed normalized input."""
         tokens = list(normalized_input.roman_tokens)
@@ -218,8 +240,9 @@ class BatchAnalysisService:
                 given_tokens,
                 tokens,
                 normalized_input.norm_map,
-                False,
-                original_compound_format,
+                is_all_chinese=False,
+                original_compound_format=original_compound_format,
+                allow_guarded_given_first_bonus=allow_guarded_given_first_bonus,
             )
 
             # Determine the format of this parse
@@ -240,6 +263,136 @@ class BatchAnalysisService:
         best_candidate = candidates[0] if candidates else None
         return candidates, best_candidate
 
+    def _promote_guarded_given_first_batch_votes(
+        self,
+        name_candidates: list[tuple[str, list[ParseCandidate], ParseCandidate | None, dict | None]],
+        normalizer,
+        data,
+    ) -> list[tuple[str, list[ParseCandidate], ParseCandidate | None, dict | None]]:
+        """Promote contested given-first votes when batch-level shape evidence supports them."""
+        participant_count = sum(1 for _name, candidates, best_candidate, _ in name_candidates if candidates and best_candidate)
+        if participant_count == 0:
+            return name_candidates
+
+        promoted, first_surname_freqs, given_shape_count = self._collect_guarded_given_first_promotions(
+            name_candidates,
+            normalizer,
+            data,
+        )
+
+        if not self._should_promote_guarded_given_first_votes(
+            participant_count,
+            promoted,
+            first_surname_freqs,
+            given_shape_count,
+        ):
+            return name_candidates
+
+        adjusted = list(name_candidates)
+        for index, promoted_candidate in promoted:
+            name, candidates, _best_candidate, compound_metadata = adjusted[index]
+            adjusted[index] = (name, candidates, promoted_candidate, compound_metadata)
+        return adjusted
+
+    def _collect_guarded_given_first_promotions(
+        self,
+        name_candidates: list[tuple[str, list[ParseCandidate], ParseCandidate | None, dict | None]],
+        normalizer,
+        data,
+    ) -> tuple[list[tuple[int, ParseCandidate]], list[float], int]:
+        """Collect given-first candidates that only become best under individual guarded scoring."""
+        promoted: list[tuple[int, ParseCandidate]] = []
+        first_surname_freqs: list[float] = []
+        given_shape_count = 0
+
+        for index, (name, candidates, best_candidate, _compound_metadata) in enumerate(name_candidates):
+            promotion = self._guarded_given_first_promotion(name, candidates, best_candidate, normalizer, data)
+            if promotion is None:
+                continue
+
+            promoted_candidate, first_token, first_norm = promotion
+            promoted.append((index, promoted_candidate))
+            first_surname_freqs.append(data.get_surname_freq(first_norm))
+            if self._has_given_name_shape(first_token):
+                given_shape_count += 1
+
+        return promoted, first_surname_freqs, given_shape_count
+
+    def _guarded_given_first_promotion(
+        self,
+        name: str,
+        candidates: list[ParseCandidate],
+        best_candidate: ParseCandidate | None,
+        normalizer,
+        data,
+    ) -> tuple[ParseCandidate, str, str] | None:
+        """Return the promoted given-first candidate and first-token evidence, if any."""
+        if not candidates or best_candidate is None or best_candidate.format != NameFormat.SURNAME_FIRST:
+            return None
+
+        normalized_input = normalizer.apply(name)
+        tokens = list(normalized_input.roman_tokens)
+        if len(tokens) != TWO_TOKEN_NAME_LENGTH:
+            return None
+
+        _individual_candidates, individual_best = self._analyze_individual_name_with_normalized(
+            name,
+            normalized_input,
+            data,
+            allow_guarded_given_first_bonus=True,
+        )
+        if individual_best is None or individual_best.format != NameFormat.GIVEN_FIRST:
+            return None
+
+        promoted_candidate = self._matching_given_first_candidate(candidates, individual_best)
+        if promoted_candidate is None:
+            return None
+
+        first_token = tokens[0]
+        first_norm = normalizer.get_normalized(first_token, normalized_input.norm_map).replace(" ", "")
+        return promoted_candidate, first_token, first_norm
+
+    @staticmethod
+    def _matching_given_first_candidate(
+        candidates: list[ParseCandidate],
+        individual_best: ParseCandidate,
+    ) -> ParseCandidate | None:
+        """Find the no-bonus candidate that matches the individual guarded winner."""
+        return next(
+            (
+                candidate
+                for candidate in candidates
+                if candidate.format == NameFormat.GIVEN_FIRST
+                and candidate.surname_tokens == individual_best.surname_tokens
+                and candidate.given_tokens == individual_best.given_tokens
+            ),
+            None,
+        )
+
+    @staticmethod
+    def _should_promote_guarded_given_first_votes(
+        participant_count: int,
+        promoted: list[tuple[int, ParseCandidate]],
+        first_surname_freqs: list[float],
+        given_shape_count: int,
+    ) -> bool:
+        """Return whether guarded given-first votes have enough batch-level support."""
+        if not promoted or len(promoted) / participant_count < GUARDED_GIVEN_FIRST_BATCH_MIN_SHARE:
+            return False
+
+        has_shape_evidence = given_shape_count / len(promoted) >= GIVEN_NAME_SHAPE_MIN_SHARE
+        has_ultra_low_first_surname_evidence = (
+            bool(first_surname_freqs)
+            and median(first_surname_freqs) < ULTRA_LOW_FIRST_SURNAME_MEDIAN_MAX
+        )
+        return has_shape_evidence or has_ultra_low_first_surname_evidence
+
+    @staticmethod
+    def _has_given_name_shape(token: str) -> bool:
+        """Return whether a token has independent shape evidence for given-name position."""
+        raw = token.replace("-", "").replace("'", "")
+        return len(raw) >= LONG_GIVEN_NAME_TOKEN_MIN_LENGTH
+
     def _determine_parse_format(
         self, surname_tokens: list[str], _given_tokens: list[str], original_tokens: list[str],
     ) -> NameFormat:

{sinonym-0.2.4 → sinonym-0.2.5}/sinonym/services/formatting.py

@@ -86,6 +86,14 @@ class NameFormattingService:
                 self._normalizer,
                 self._config,
             )
+            if not split:
+                split = StringManipulationUtils.split_surname_like_given_name(
+                    token,
+                    normalized_cache,
+                    self._data,
+                    self._normalizer,
+                    self._config,
+                )
             if split:
                 parts.extend(split)
             # Final validation: accept if it's a valid Chinese token
@@ -217,8 +225,20 @@ class NameFormattingService:
                 continue
 
             split = StringManipulationUtils.split_concatenated_name(
-                token, normalized_cache, self._data, self._normalizer, self._config,
+                token,
+                normalized_cache,
+                self._data,
+                self._normalizer,
+                self._config,
             )
+            if not split:
+                split = StringManipulationUtils.split_surname_like_given_name(
+                    token,
+                    normalized_cache,
+                    self._data,
+                    self._normalizer,
+                    self._config,
+                )
             if split:
                 parts.extend(split)
             elif self._normalizer.is_valid_given_name_token(token, normalized_cache):

{sinonym-0.2.4 → sinonym-0.2.5}/sinonym/services/parsing.py

@@ -18,6 +18,10 @@ from sinonym.utils.string_manipulation import StringManipulationUtils
 if TYPE_CHECKING:
     from sinonym.services.normalization import CompoundMetadata
 
+LOW_FREQUENCY_SURNAME_MAX = 500.0
+GIVEN_FIRST_SURNAME_FREQ_RATIO_MIN = 50.0
+GIVEN_FIRST_ORDER_PRESERVATION_BONUS = 4.0
+
 
 class NameParsingService:
     """Service for parsing Chinese names into surname and given name components."""
@@ -110,7 +114,13 @@ class NameParsingService:
             given_tokens = order[given_slice]
             if given_tokens:
                 # Check if this parse would have a reasonable score
-                score = self.calculate_parse_score(surname_tokens, given_tokens, order, normalized_cache, False)
+                score = self.calculate_parse_score(
+                    surname_tokens,
+                    given_tokens,
+                    order,
+                    normalized_cache,
+                    is_all_chinese=False,
+                )
 
                 # Western name detection pattern
                 has_single_letter_given = any(len(token) == 1 for token in given_tokens)
@@ -159,7 +169,13 @@ class NameParsingService:
             surname_tokens = [surname_token]
             given_tokens = order[given_slice]
             if given_tokens:
-                score = self.calculate_parse_score(surname_tokens, given_tokens, order, normalized_cache, False)
+                score = self.calculate_parse_score(
+                    surname_tokens,
+                    given_tokens,
+                    order,
+                    normalized_cache,
+                    is_all_chinese=False,
+                )
 
                 has_single_letter_given = any(len(token) == 1 for token in given_tokens)
                 has_multi_syllable_tokens = any(len(token) > 3 for token in order)
@@ -246,8 +262,8 @@ class NameParsingService:
                 given_tokens,
                 tokens,
                 normalized_cache,
-                False,
-                original_compound_format,
+                is_all_chinese=False,
+                original_compound_format=original_compound_format,
                 score_cache=score_cache,
             )
 
@@ -351,8 +367,8 @@ class NameParsingService:
                 given_tokens,
                 tokens,
                 normalized_cache,
-                False,
-                original_compound_format,
+                is_all_chinese=False,
+                original_compound_format=original_compound_format,
                 score_cache=score_cache,
             )
 
@@ -536,9 +552,11 @@ class NameParsingService:
         given_tokens: list[str],
         tokens: list[str],
         normalized_cache: dict[str, str],
+        *,
         is_all_chinese: bool = False,
         original_compound_format: str | None = None,
         score_cache: dict[str, dict] | None = None,
+        allow_guarded_given_first_bonus: bool = True,
     ) -> float:
         """Calculate unified score for a parse candidate."""
         if not given_tokens:
@@ -617,6 +635,12 @@ class NameParsingService:
 
                 if is_ambiguous:
                     order_preservation_bonus = 1.0  # Strong bonus for preserving original order in ambiguous cases
+                elif allow_guarded_given_first_bonus and self._has_guarded_given_first_surname_ratio(
+                    surname_tokens[0],
+                    given_tokens[0],
+                    normalized_cache,
+                ):
+                    order_preservation_bonus = GIVEN_FIRST_ORDER_PRESERVATION_BONUS
         if not is_all_chinese and len(tokens) == 3 and len(surname_tokens) == 1 and len(given_tokens) == 2:
             # Narrow extension for hard 3-token given-first cases:
             # only apply when surname-last is materially more plausible than surname-first.
@@ -724,6 +748,39 @@ class NameParsingService:
         freq_ratio = max(surname_freq, given_freq) / min(surname_freq, given_freq)
         return freq_ratio < 5.0  # Ambiguous if frequencies are within 5x of each other
 
+    def _has_guarded_given_first_surname_ratio(
+        self,
+        surname_token: str,
+        given_token: str,
+        normalized_cache: dict[str, str],
+    ) -> bool:
+        """Return whether surname frequencies strongly support given-first order."""
+        if "-" in given_token or self._is_compound_surname_token(given_token, normalized_cache):
+            return False
+
+        surname_key = self._surname_key([surname_token], normalized_cache)
+        given_as_surname_key = self._surname_key([given_token], normalized_cache)
+
+        if not (
+            self._data.is_surname(surname_token, surname_key)
+            and self._data.is_surname(given_token, given_as_surname_key)
+        ):
+            return False
+
+        given_surname_freq = self._data.get_surname_freq(given_as_surname_key)
+        surname_freq = self._data.get_surname_freq(surname_key)
+        if not (0 < given_surname_freq < LOW_FREQUENCY_SURNAME_MAX):
+            return False
+
+        return surname_freq / given_surname_freq > GIVEN_FIRST_SURNAME_FREQ_RATIO_MIN
+
+    def _is_compound_surname_token(self, token: str, _normalized_cache: dict[str, str]) -> bool:
+        """Return whether a single token is a known compact/camelCase compound surname."""
+        token_key = token.strip().lower()
+        return token_key in COMPOUND_VARIANTS or (
+            "-" in token_key and token_key in self._data.compound_hyphen_map
+        )
+
     def _surname_key(self, surname_tokens: list[str], normalized_cache: dict[str, str]) -> str:
         """Convert surname tokens to lookup key, preferring Chinese characters when available."""
         if len(surname_tokens) == 1:

{sinonym-0.2.4 → sinonym-0.2.5}/sinonym/utils/string_manipulation.py

@@ -20,11 +20,14 @@ from functools import lru_cache
 from typing import TYPE_CHECKING
 
 # Import at module level to avoid repeated imports in hot paths
-from sinonym.chinese_names_data import HIGH_CONFIDENCE_ANCHORS
+from sinonym.chinese_names_data import COMPOUND_VARIANTS, HIGH_CONFIDENCE_ANCHORS
 
 if TYPE_CHECKING:
     from sinonym.services.normalization import CompoundMetadata
 
+MIN_SPLIT_TOKEN_LENGTH = 3
+MAX_UNBALANCED_SPLIT_REST_LENGTH = 4
+
 
 class StringManipulationUtils:
     """Centralized utilities for string manipulation in Chinese name processing."""
@@ -122,10 +125,45 @@ class StringManipulationUtils:
         return False
 
     @staticmethod
-    def _should_skip_splitting(token: str, normalized_cache: dict[str, str] | None, normalizer, data_context) -> bool:
+    def _high_confidence_given_split(
+        token: str,
+        normalized_cache: dict[str, str] | None,
+        normalizer,
+        data_context,
+        config,
+    ) -> list[str] | None:
+        """Return the gold-standard two-part split for a given token, if one exists."""
+        raw = token.translate(config.hyphens_apostrophes_tr)
+        for i in range(1, len(raw)):
+            a, b = raw[:i], raw[i:]
+
+            if len(a) == 1 and len(b) > MAX_UNBALANCED_SPLIT_REST_LENGTH:
+                continue
+            if len(b) == 1 and len(a) > MAX_UNBALANCED_SPLIT_REST_LENGTH:
+                continue
+
+            norm_a, norm_b = StringManipulationUtils._get_normalized_parts(a, b, normalized_cache, normalizer)
+            if norm_a not in HIGH_CONFIDENCE_ANCHORS or norm_b not in HIGH_CONFIDENCE_ANCHORS:
+                continue
+            if not StringManipulationUtils._is_valid_component_pair(norm_a, norm_b, data_context, a, b):
+                continue
+            if not StringManipulationUtils.is_plausible_chinese_split(norm_a, norm_b, data_context, config):
+                continue
+
+            return [a, b]
+
+        return None
+
+    @staticmethod
+    def _should_skip_splitting(
+        token: str,
+        normalized_cache: dict[str, str] | None,
+        normalizer,
+        data_context,
+    ) -> bool:
         """Check early exit conditions that prevent splitting - optimized validation chain."""
         # Early exit for very short tokens - no point splitting < 3 chars
-        if len(token) < 3:
+        if len(token) < MIN_SPLIT_TOKEN_LENGTH:
             return True
 
         # Get normalized form once - use eager cache for performance
@@ -136,10 +174,11 @@ class StringManipulationUtils:
 
         # Optimized validation chain: combine multiple checks with OR short-circuit
         original_lower = token.lower()
+        is_surname = tok_normalized in data_context.surnames_normalized
 
         return (
             # Don't split known surnames
-            tok_normalized in data_context.surnames_normalized or
+            is_surname or
             # Don't split HIGH_CONFIDENCE_ANCHORS - they should remain intact
             tok_normalized in HIGH_CONFIDENCE_ANCHORS or
             # Don't split existing valid Chinese given name components
@@ -147,6 +186,42 @@ class StringManipulationUtils:
             data_context.is_given_name(original_lower)
         )
 
+    @staticmethod
+    def split_surname_like_given_name(
+        token: str,
+        normalized_cache: dict[str, str] | None,
+        data_context,
+        normalizer,
+        config,
+    ) -> list[str] | None:
+        """Split a given-position token that collides with a surname only on gold evidence."""
+        if not data_context or len(token) < MIN_SPLIT_TOKEN_LENGTH:
+            return None
+
+        if normalized_cache and token in normalized_cache:
+            tok_normalized = StringManipulationUtils.remove_spaces(normalized_cache[token])
+        else:
+            tok_normalized = StringManipulationUtils.remove_spaces(normalizer.norm(token))
+
+        original_lower = token.lower()
+        if tok_normalized not in data_context.surnames_normalized:
+            return None
+        if (
+            original_lower in COMPOUND_VARIANTS
+            or original_lower in data_context.compound_original_format_map
+            or tok_normalized in COMPOUND_VARIANTS
+            or tok_normalized in data_context.compound_original_format_map
+        ):
+            return None
+
+        return StringManipulationUtils._high_confidence_given_split(
+            token,
+            normalized_cache,
+            normalizer,
+            data_context,
+            config,
+        )
+
     @staticmethod
     def _check_cultural_plausibility_if_needed(norm_a: str, norm_b: str, data_context, config, raw_length: int) -> bool:
         """Check cultural plausibility only if the raw token is long enough."""

{sinonym-0.2.4 → sinonym-0.2.5}/tests/test_all_chinese_inputs.py

@@ -53,6 +53,9 @@ ALL_CHINESE_INPUT_TEST_CASES = [
     ("張偉", (True, "Wei Zhang")),  # Traditional Zhang Wei
     ("劉強", (True, "Qiang Liu")),  # Traditional Liu Qiang
 
+    # Explicit whitespace can separate given-first all-Chinese groups
+    ("\u589e\u53cb  \u53f6", (True, "Zeng-You Ye")),
+
     # Three character names should fall back to original logic (not handled by special all-Chinese logic)
     ("李明华", (True, "Ming-Hua Li")),  # 3 characters should use existing logic
     ("王小明", (True, "Xiao-Ming Wang")),  # 3 characters should use existing logic

{sinonym-0.2.4 → sinonym-0.2.5}/tests/test_regression_proposals.py

@@ -125,6 +125,124 @@ def test_three_token_order_preservation_regression(detector):
     assert clear.result == "Wei-Ming Zhang"
 
 
+def test_guarded_low_frequency_surname_ratio_preserves_given_first_order(detector):
+    cases = {
+        "Bei Yu": "Bei Yu",
+        "Lecheng Zheng": "Lecheng Zheng",
+        "Yuxuan Dong": "Yuxuan Dong",
+        "Xun Zhou": "Xun Zhou",
+        "mi zhang": "Mi Zhang",
+    }
+
+    for raw_name, expected in cases.items():
+        result = detector.normalize_name(raw_name)
+        assert result.success
+        assert result.result == expected
+
+
+def test_batch_format_detection_ignores_isolated_low_frequency_surname_ratio(detector):
+    names = ["Diao Wang", "Bian Li", "Cen Zhang", "Luan Wang", "Rao Li"]
+    expected_results = ["Wang Diao", "Li Bian", "Zhang Cen", "Wang Luan", "Li Rao"]
+
+    pattern = detector.detect_batch_format(names)
+    batch = detector.analyze_name_batch(names)
+
+    assert pattern.dominant_format == NameFormat.SURNAME_FIRST
+    assert pattern.threshold_met
+    assert batch.format_pattern.dominant_format == NameFormat.SURNAME_FIRST
+    assert [result.result for result in batch.results] == expected_results
+    assert all(result.parsed_original_order.order == ["surname", "given"] for result in batch.results)
+
+
+def test_batch_preserves_homogeneous_guarded_given_first_ratio_names(detector):
+    names = ["Bei Yu", "Lecheng Zheng", "Yuxuan Dong", "Xun Zhou"]
+    expected_results = ["Bei Yu", "Lecheng Zheng", "Yuxuan Dong", "Xun Zhou"]
+
+    batch = detector.analyze_name_batch(names)
+
+    assert [result.result for result in batch.results] == expected_results
+    assert all(result.parsed_original_order.order == ["given", "surname"] for result in batch.results)
+
+
+def test_guarded_low_frequency_surname_ratio_keeps_compound_and_common_surname_boundaries(detector):
+    cases = {
+        "Men Hao": "Hao Men",
+        "Ouyang Xiu": "Xiu Ouyang",
+        "Murong Xue": "Xue Murong",
+    }
+
+    for raw_name, expected in cases.items():
+        result = detector.normalize_name(raw_name)
+        assert result.success
+        assert result.result == expected
+
+
+def test_given_context_gold_split_bypasses_surname_guard(detector):
+    cases = {
+        "Junjie Fang": "Jun-Jie Fang",
+        "Junjie Peng": "Jun-Jie Peng",
+        "Junjie Ye": "Jun-Jie Ye",
+    }
+
+    for raw_name, expected in cases.items():
+        result = detector.normalize_name(raw_name)
+        assert result.success
+        assert result.result == expected
+
+
+def test_batch_preserves_homogeneous_given_context_gold_splits(detector):
+    names = ["Junjie Fang", "Junjie Peng", "Junjie Ye"]
+    expected_results = ["Jun-Jie Fang", "Jun-Jie Peng", "Jun-Jie Ye"]
+
+    batch = detector.analyze_name_batch(names)
+
+    assert [result.result for result in batch.results] == expected_results
+    assert all(result.parsed_original_order.order == ["given", "surname"] for result in batch.results)
+
+
+def test_given_context_gold_split_is_used_by_string_formatter(detector):
+    normalized = detector._normalizer.apply("Junjie Fang")
+
+    formatted = detector._formatting_service.format_name_output(
+        ["Fang"],
+        ["Junjie"],
+        normalized.norm_map,
+        {},
+    )
+
+    assert formatted == "Jun-Jie Fang"
+
+
+def test_given_context_gold_split_keeps_ambiguous_non_gold_tokens_unsplit(detector):
+    splitter = StringManipulationUtils.split_concatenated_name
+    data = detector._data
+    normalizer = detector._normalizer
+    config = detector._config
+
+    junjie = normalizer.apply("Junjie")
+    assert splitter("Junjie", junjie.norm_map, data, normalizer, config) is None
+    assert StringManipulationUtils.split_surname_like_given_name(
+        "Junjie",
+        junjie.norm_map,
+        data,
+        normalizer,
+        config,
+    ) == ["Jun", "jie"]
+
+    for token in ["Yuxuan", "Lecheng"]:
+        normalized = normalizer.apply(token)
+        assert (
+            StringManipulationUtils.split_surname_like_given_name(
+                token,
+                normalized.norm_map,
+                data,
+                normalizer,
+                config,
+            )
+            is None
+        )
+
+
 def test_two_token_format_alignment_tie_break_is_directional(detector):
     parsing = detector._parsing_service
 
@@ -372,6 +490,58 @@ def test_han_conversion_parity_across_all_chinese_flag(detector):
         assert all_chinese_path == mixed_path
 
 
+def test_spaced_all_chinese_given_first_preserves_group_boundary(detector):
+    result = detector.normalize_name("\u589e\u53cb  \u53f6")
+
+    assert result.success
+    assert result.result == "Zeng-You Ye"
+    assert result.parsed.surname == "Ye"
+    assert result.parsed.given_name == "Zeng-You"
+    assert result.parsed_original_order.order == ["given", "surname"]
+
+
+def test_spaced_all_chinese_regular_surname_first_preserves_group_boundary(detector):
+    result = detector.normalize_name("\u674e \u660e\u534e")
+
+    assert result.success
+    assert result.result == "Ming-Hua Li"
+    assert result.parsed.surname == "Li"
+    assert result.parsed.given_name == "Ming-Hua"
+    assert result.parsed_original_order.order == ["surname", "given"]
+
+
+@pytest.mark.parametrize(
+    ("raw_name", "expected"),
+    [
+        ("\u738b \u6b27\u9633", "Wang Ou Yang"),
+        ("\u674e \u6b27\u9633", "Li Ou Yang"),
+        ("\u6797 \u8bf8\u845b", "Lin Zhu Ge"),
+    ],
+)
+def test_spaced_all_chinese_prefers_trailing_compound_surname(detector, raw_name, expected):
+    result = detector.normalize_name(raw_name)
+
+    assert result.success
+    assert result.result == expected
+    assert result.parsed_original_order.order == ["given", "surname"]
+
+
+@pytest.mark.parametrize(
+    ("raw_name", "expected"),
+    [
+        ("\u53f8 \u9a6c\u534e", "Hua Si Ma"),
+        ("\u6b27 \u9633\u660e", "Ming Ou Yang"),
+        ("\u8bf8 \u845b\u4eae", "Liang Zhu Ge"),
+    ],
+)
+def test_spaced_all_chinese_preserves_compound_surname_boundary(detector, raw_name, expected):
+    result = detector.normalize_name(raw_name)
+
+    assert result.success
+    assert result.result == expected
+    assert result.parsed_original_order.order == ["surname", "given"]
+
+
 def test_name_data_structures_mapping_fields_are_immutable(detector):
     data = detector._data
     mapping_fields = [