feat(naming): homophone detection with probabilities

Add realnames.homophones(name, country) — groups same-sounding names in a
country by double-metaphone and weights each by country-wide frequency share,
returning probabilities that sum to 1. E.g. Dominique/FR ->
Dominique 0.91, Dominic 0.03, Dominik 0.02, ...

Dataset gains two columns (parquet rebuilt, 18.8MB): country_share (relative
share within a country, cross-gender comparable, still no raw counts) and
phonetic (double-metaphone). Tests + README updated; naming coverage 97%.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jqueguiner

README.md

@@ -39,6 +39,7 @@ realnames.first_name_like("Jacques", "FR")    # frequency-weighted male FR name
 realnames.first_name("JP", "f")               # weighted female Japanese name
 realnames.detect_country("Yuki")              # [("JP", 0.58), ("CN", 0.05), ...]
 realnames.detect_country("Bjorn")             # [("SE", 0.29), ("NO", 0.22), ...]
+realnames.homophones("Dominique", "FR")       # [("Dominique", 0.91), ("Dominic", 0.03), ...]
 
 grammar.pluralize("baby")                     # "babies"
 grammar.agree(3, "dog")                       # "3 dogs"
@@ -51,6 +52,10 @@ variant `faker2.naming.gender` has no extra dependency.
 frequency share), not where the most *people* with that name live — raw
 population counts are intentionally not in the dataset.
 
+`homophones` groups same-sounding names in a country by double-metaphone and
+weights them by frequency share (probabilities sum to 1). Double-metaphone is
+coarse, so results may include near-homophones.
+
 ## Rust port
 
 ```

data/README.md

@@ -15,7 +15,11 @@ Format: Parquet, zstd-compressed, dictionary-encoded low-cardinality columns.
 
 ## Schema (`first_names`)
 
-`name, name_ascii, country_code, country_name, continent, gender, unisex, country_rank, frequency`
+`name, name_ascii, country_code, country_name, continent, gender, unisex, country_rank, frequency, country_share, phonetic`
+
+- `frequency` — relative share within `(country_code, gender)` (weighted sampling).
+- `country_share` — relative share within `country_code` (cross-gender comparable; powers `detect_country` / `homophones` probabilities).
+- `phonetic` — double-metaphone key (powers `homophones`).
 
 `frequency` is a **relative share** (0..1) within each `(country_code, gender)`
 group — it preserves the weighting used for sampling but deliberately carries

data/first_names.parquet

@@ -38,13 +38,19 @@ def __init__(self, path: str = _DATA) -> None:
         import pyarrow.parquet as pq  # local import: optional dependency
 
         tbl = pq.read_table(
-            path, columns=["name", "name_ascii", "country_code", "gender", "frequency"]
+            path,
+            columns=[
+                "name", "name_ascii", "country_code", "gender",
+                "frequency", "country_share", "phonetic",
+            ],
         )
         names = tbl.column("name").to_pylist()
         asciis = tbl.column("name_ascii").to_pylist()
         ccs = tbl.column("country_code").to_pylist()
         genders = tbl.column("gender").to_pylist()
         freqs = tbl.column("frequency").to_pylist()
+        shares = tbl.column("country_share").to_pylist()
+        phonetics = tbl.column("phonetic").to_pylist()
 
         # (country, gender) -> (names[], cumulative_weights[]).
         # Weights are *relative* frequencies (shares), never raw counts.
@@ -53,12 +59,21 @@ def __init__(self, path: str = _DATA) -> None:
         gender_by: Dict[Tuple[str, Optional[str]], Dict[str, float]] = {}
         # name_key -> {country: summed within-country share} for origin detection
         country_by: Dict[str, Dict[str, float]] = {}
+        # (name_key, country) -> phonetic key; (country, phonetic) -> {name: share}
+        phon_key: Dict[Tuple[str, str], str] = {}
+        homo: Dict[Tuple[str, str], Dict[str, float]] = {}
 
         acc: Dict[Tuple[Optional[str], str], List] = {}
-        for name, asc, cc, g, fr in zip(names, asciis, ccs, genders, freqs):
+        for name, asc, cc, g, fr, cs, phon in zip(
+            names, asciis, ccs, genders, freqs, shares, phonetics
+        ):
             if not g or g == " ":
                 continue
             w = float(fr) if fr else 1e-6
+            csh = float(cs) if cs else 1e-9
+            if cc and phon:
+                homo.setdefault((cc, phon), {})
+                homo[(cc, phon)][name] = homo[(cc, phon)].get(name, 0.0) + csh
             for scope in (cc, None):  # per-country and global pools
                 key = (scope, g)
                 lst = acc.setdefault(key, [[], []])
@@ -72,6 +87,8 @@ def __init__(self, path: str = _DATA) -> None:
                 if cc:
                     c = country_by.setdefault(akey, {})
                     c[cc] = c.get(cc, 0.0) + w
+                    if phon:
+                        phon_key[(akey, cc)] = phon
 
         # finalize cumulative weights for O(log n) weighted draw
         for key, (nm, wt) in acc.items():
@@ -84,6 +101,8 @@ def __init__(self, path: str = _DATA) -> None:
         self._pools = pools
         self._gender_by = gender_by
         self._country_by = country_by
+        self._phon_key = phon_key
+        self._homo = homo
 
     def infer(self, name: str, country: Optional[str] = None) -> Optional[str]:
         key = name.strip().lower()
@@ -119,6 +138,29 @@ def draw(self, country: Optional[str], gender: str, avoid: Optional[str] = None)
     def countries(self) -> List[str]:
         return sorted({cc for (cc, _g) in self._pools if cc})
 
+    def homophones(
+        self, name: str, country: str, top: int = 10, include_self: bool = True
+    ) -> List[Tuple[str, float]]:
+        """Names that sound like ``name`` in ``country``, with probabilities.
+
+        Groups names by phonetic key (double-metaphone) within the country and
+        weights each by its country-wide frequency share. Returns
+        ``[(name, probability)]`` (probabilities over the group sum to 1),
+        highest first.
+        """
+        phon = self._phon_key.get((name.strip().lower(), country))
+        if not phon:
+            return []
+        group = self._homo.get((country, phon))
+        if not group:
+            return []
+        items = list(group.items())
+        if not include_self:
+            items = [(n, w) for n, w in items if n.lower() != name.strip().lower()]
+        total = sum(w for _n, w in items) or 1.0
+        ranked = sorted(items, key=lambda kv: kv[1], reverse=True)
+        return [(n, w / total) for n, w in ranked[:top]]
+
     def detect_country(self, name: str, top: int = 5) -> List[Tuple[str, float]]:
         """Rank the countries where ``name`` is most characteristic.
 
@@ -158,6 +200,20 @@ def detect_country(name: str, top: int = 5) -> List[Tuple[str, float]]:
     return _bank().detect_country(name, top)
 
 
+def homophones(
+    name: str, country: str, top: int = 10, include_self: bool = True
+) -> List[Tuple[str, float]]:
+    """Same-sounding names in a country, with probabilities.
+
+        homophones("Dominique", "FR")
+        # [("Dominique", 0.91), ("Dominic", 0.03), ("Dominik", 0.02), ...]
+
+    Groups by double-metaphone within ``country`` and weights by country-wide
+    frequency share. Probabilities sum to 1. ``[]`` if the name is unknown.
+    """
+    return _bank().homophones(name, country.upper() if country else "", top, include_self)
+
+
 def first_name(country: Optional[str] = None, gender: str = MALE) -> Optional[str]:
     """Frequency-weighted first name for a country + gender."""
     return _bank().draw(country.upper() if country else None, gender)

faker2/naming/realnames.py

@@ -73,6 +73,22 @@ def test_detect_country():
     assert len(rn.detect_country("Maria", top=2)) <= 2 # top-N respected
 
 
+def test_homophones():
+    h = rn.homophones("Dominique", "FR", top=6)
+    names = [n for n, _p in h]
+    assert h[0][0] == "Dominique"                       # most frequent variant first
+    assert "Dominic" in names and "Dominik" in names    # same-sounding variants
+    assert abs(sum(p for _n, p in rn.homophones("Dominique", "FR", top=999)) - 1.0) < 1e-6
+    # symmetric: Dominic sees the same group
+    assert "Dominique" in [n for n, _ in rn.homophones("Dominic", "FR")]
+    # exclude_self drops the query name
+    assert "Dominique" not in [
+        n for n, _ in rn.homophones("Dominique", "FR", include_self=False)
+    ]
+    assert rn.homophones("Zzxqwv", "FR") == []          # unknown -> empty
+    assert len(rn.homophones("Marc", "FR", top=3)) <= 3 # top-N respected
+
+
 def test_seed_reproducible():
     Faker.seed(99)
     a = [rn.first_name_like("Jacques", "FR") for _ in range(5)]