sinonym 0.2.4__tar.gz → 0.2.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sinonym
-Version: 0.2.4
+Version: 0.2.7
 Summary: Chinese Name Detection and Normalization Module
 Project-URL: Homepage, https://github.com/allenai/sinonym
 Project-URL: Repository, https://github.com/allenai/sinonym
@@ -21,6 +21,7 @@ Classifier: Topic :: Text Processing :: Linguistic
 Requires-Python: >=3.10
 Requires-Dist: joblib>=1.3
 Requires-Dist: numpy>=1.24
+Requires-Dist: pydantic<2,>=1.10
 Requires-Dist: pypinyin>=0.44.0
 Requires-Dist: requests>=2.31
 Requires-Dist: scikit-learn<2,>=1.2

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sinonym"
-version = "0.2.4"
+version = "0.2.7"
 description = "Chinese Name Detection and Normalization Module"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -27,6 +27,7 @@ keywords = ["chinese", "names", "nlp", "romanization", "pinyin"]
 dependencies = [
     "joblib>=1.3",
     "numpy>=1.24",
+    "pydantic>=1.10,<2",
     "pypinyin>=0.44.0",
     "requests>=2.31",
     "scikit-learn>=1.2,<2",

{sinonym-0.2.4 → sinonym-0.2.7}/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.7}/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.7}/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.7}/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.7}/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.7/sinonym/timo/config.yaml

@@ -0,0 +1,12 @@
+config_version: 0.0.1
+model_variants:
+  sinonym_v1:
+    instance: sinonym.timo.interface.Instance
+    prediction: sinonym.timo.interface.Prediction
+    predictor: sinonym.timo.interface.Predictor
+    predictor_config: sinonym.timo.interface.PredictorConfig
+    artifacts_s3_path: null
+    python_version: "3.10"
+    cuda: False
+    integration_test: sinonym.timo.integration_test.TestIntegration
+    docker_run_commands: []

sinonym-0.2.7/sinonym/timo/integration_test.py

@@ -0,0 +1,70 @@
+import unittest
+
+from sinonym.timo.interface import Instance, Prediction, Predictor, PredictorConfig
+
+
+class TestIntegration(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.predictor = Predictor(config=PredictorConfig(), artifacts_dir=".")
+
+    def test_chinese_name(self):
+        results = self.predictor.predict_batch([Instance(name="Li Wei")])
+        self.assertEqual(len(results), 1)
+        self.assertIsInstance(results[0], Prediction)
+        self.assertTrue(results[0].success)
+        self.assertIsNotNone(results[0].given_name)
+        self.assertIsNotNone(results[0].surname)
+
+    def test_non_chinese_name(self):
+        results = self.predictor.predict_batch([Instance(name="John Smith")])
+        self.assertEqual(len(results), 1)
+        self.assertFalse(results[0].success)
+        self.assertIsNotNone(results[0].error_message)
+
+    def test_batch_superset_output(self):
+        instances = [Instance(name="Li Wei"), Instance(name="Wang Weiming")]
+        results = self.predictor.predict_batch(instances)
+        self.assertEqual(len(results), 2)
+        for r in results:
+            self.assertIsInstance(r, Prediction)
+            self.assertTrue(r.success)
+            # superset: every Prediction carries confidence + format_pattern
+            self.assertIsNotNone(r.confidence)
+            self.assertIsNotNone(r.format_pattern)
+        # shared batch pattern replicated onto each row
+        self.assertEqual(
+            results[0].format_pattern.dominant_format,
+            results[1].format_pattern.dominant_format,
+        )
+
+    def test_predict_batch_empty(self):
+        self.assertEqual(self.predictor.predict_batch([]), [])
+
+    def test_score_name_batch(self):
+        names = ["Li Wei", "Wang Weiming"]
+        summary = self.predictor.score_name_batch(names)
+        self.assertEqual(summary.names, names)
+        self.assertEqual(len(summary.results), 2)
+        self.assertEqual(len(summary.confidences), 2)
+        self.assertIsNotNone(summary.format_pattern.dominant_format)
+
+    def test_score_name_batch_tuned_threshold(self):
+        names = ["Li Wei", "Wang Weiming"]
+        summary = self.predictor.score_name_batch(names, format_threshold=0.9)
+        self.assertEqual(len(summary.results), 2)
+        self.assertEqual(
+            summary.format_pattern.threshold_met,
+            summary.format_pattern.confidence >= 0.9,
+        )
+
+    def test_detect_batch_format(self):
+        pattern = self.predictor.detect_batch_format(["Zhang Wei", "Li Ming", "Wang Xiaoli"])
+        self.assertIn(
+            pattern.dominant_format, {"surname_first", "given_first", "mixed"}
+        )
+
+    def test_analyze_name_batch_full(self):
+        result = self.predictor.analyze_name_batch(["Li Wei", "Wang Weiming"])
+        self.assertEqual(len(result.results), 2)
+        self.assertEqual(len(result.individual_analyses), 2)