Report the ambiguous-suffix readings instead of guessing silently

particles_ambiguous emitted PARTICLE_OR_GIVEN; suffix_acronyms_ambiguous
emitted nothing, for the structurally identical situation -- a word in
an ambiguous vocabulary where the parser picks one of two readings.
"parse('derek gulbranson MA').ambiguities" was empty even though the
parser had just chosen credential over surname.

Two kinds now emit:

SUFFIX_OR_FAMILY (new) at the peel in _assign, in BOTH directions --
"John Smith MA" reports that MA was read as a suffix, "Jack MA" that it
was read as the family name. Both are guesses.

SUFFIX_OR_NICKNAME (reserved since the core API landed) at classify,
for delimited content the vocabulary cannot settle: "(MBA)" escapes to
suffix on vocabulary alone, so "(JD)" keeping the nickname reading was
a silent coin-flip. Emitted at classify rather than at the escape in
extract, which runs before tokenize and so has no token index to
point at.

The emission has to be at the DECISION site, not on tag presence. In
"Joao da Silva do Amaral de Souza" the token 'do' carries
vocab:suffix-ambiguous but sits mid-name and is never at the peel
boundary -- no choice was made, so nothing is reported. Same reasoning
excludes "Ma, Jack", where a comma fixes the family before the question
arises: that mirrors the existing rule that PARTICLE_OR_GIVEN is not
emitted on the FAMILY_COMMA path. An ambiguity is a property of a
decision, not of a token.

Corpus impact is ~1%: 5 of 486 names.

test_every_ambiguity_kind_has_a_registered_trigger caught the new kind
immediately and the case table's exact-ambiguities assertion caught all
six affected rows -- both guards did their job.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: derek73

docs/release_log.rst

@@ -24,7 +24,7 @@ Release Log
     - Add ``PatronymicRule`` with the members ``EAST_SLAVIC`` and ``TURKIC``. v1's single ``patronymic_name_order`` flag enabled both detectors at once; ``Policy(patronymic_rules=...)`` lets you enable either one alone
     - Add ``PolicyPatch`` and the ``UNSET`` sentinel for partial policy deltas that compose -- set-valued fields union, scalar fields override with later winning. This is the mechanism locale packs are built from, and ``UNSET`` is only needed when you must distinguish "not set" from a real ``False`` or ``None``
     - Add ``Token``, ``Span`` and ``Role``: every field is backed by tokens carrying exact ``(start, end)`` offsets into the original string, reachable with ``tokens_for(Role.GIVEN)``. This replaces v1's ``*_list`` attributes and makes it possible to highlight or re-slice the input the parse came from
-    - Add ``Ambiguity`` and the ``AmbiguityKind`` enum, so a parse reports what it had to guess at instead of guessing silently. The kinds emitted today are ``particle-or-given``, ``unbalanced-delimiter`` and ``comma-structure``; ``order`` and ``suffix-or-nickname`` are reserved and not yet emitted
+    - Add ``Ambiguity`` and the ``AmbiguityKind`` enum, so a parse reports what it had to guess at instead of guessing silently. The kinds emitted today are ``particle-or-given``, ``suffix-or-family``, ``suffix-or-nickname``, ``unbalanced-delimiter`` and ``comma-structure``; ``order`` is reserved and not yet emitted. The two suffix kinds cover the post-nominals that are also ordinary words: ``"John Smith MA"`` reports that ``MA`` was read as a credential rather than a surname, and ``"JEFFREY (JD) BRICKEN"`` that the delimited ``JD`` was read as a nickname rather than a suffix. A reading the vocabulary settles on its own — ``"John Smith M.A."``, ``"Andrew Perkins (MBA)"`` — is not a guess and reports nothing
     - Add ``ParsedName`` output and comparison methods: ``render(spec)``, ``initials()``, ``capitalized()`` (which returns a new value rather than mutating in place), ``as_dict()``, ``replace(**fields)``, ``matches()`` and ``comparison_key()``
     - Add ``Locale``, the public pack type. Writing your own needs no registration -- construct a ``Locale`` and pass it to ``parser_for()``
     - Ship a fully typed public API (PEP 561): the core modules are checked under strict mypy settings, and nameparser 2.0 has no runtime dependencies

docs/usage.rst

@@ -318,6 +318,27 @@ so branching on a kind needs no import:
     >>> [t.text for t in name.ambiguities[0].tokens]
     ['Van']
 
+The post-nominals that double as ordinary surnames report the same way.
+``MA`` after a full name is read as a credential, but after a single
+given name it stays the surname — either way the choice is recorded:
+
+.. doctest::
+
+    >>> parse("John Smith MA").suffix
+    'MA'
+    >>> [a.kind.value for a in parse("John Smith MA").ambiguities]
+    ['suffix-or-family']
+    >>> parse("Jack MA").family
+    'MA'
+
+A reading the vocabulary settles on its own is not a guess and reports
+nothing — periods make ``M.A.`` unambiguously a credential:
+
+.. doctest::
+
+    >>> parse("John Smith M.A.").ambiguities
+    ()
+
 Most names report none. A non-empty ``ambiguities`` is a useful signal
 for routing a record to human review instead of trusting it silently.
 

nameparser/_pipeline/_assign.py

@@ -124,6 +124,9 @@ def _assign_main(seg_idx: int, state: ParseState,
     # every piece is a strict suffix (v1's are_suffixes tail rule, with
     # the roman-numeral special: a final roman numeral after a
     # non-initial piece is a suffix)
+    # (piece, reading taken, reading declined) when the peel had to
+    # resolve a bare ambiguous acronym; both directions are guesses
+    ambiguous_pick: tuple[tuple[int, ...], str, str] | None = None
     k = len(rest)
     while k > 0:
         piece = pieces[rest[k - 1]]
@@ -145,10 +148,18 @@ def _assign_main(seg_idx: int, state: ParseState,
         # deliberately peels UNambiguous suffixes even when nothing is
         # left ("Smith PhD" -> suffix, a classified fix), because there
         # the vocabulary is not in doubt.
-        if (k - 1 >= 2 and len(piece) == 1
-                and "vocab:suffix-ambiguous" in tokens[piece[0]].tags):
+        bare_ambiguous = (len(piece) == 1
+                          and "vocab:suffix-ambiguous" in tokens[piece[0]].tags)
+        if bare_ambiguous and k - 1 >= 2:
+            ambiguous_pick = (piece, "a suffix", "an ordinary surname")
             k -= 1
             continue
+        if bare_ambiguous and k >= 2:
+            # not peeled, so it stays the last name piece -- the family
+            # name under every order. (k < 2 means it is the only piece
+            # left and lands in the given position, which is not the
+            # fork this reports.)
+            ambiguous_pick = (piece, "a family name", "a post-nominal")
         break
     name_pieces, suffix_pieces = rest[:k], rest[k:]
     if not name_pieces and suffix_pieces:
@@ -159,6 +170,14 @@ def _assign_main(seg_idx: int, state: ParseState,
         _set_roles(tokens, pieces[piece_idx], roles[pos])
     for piece_idx in suffix_pieces:
         _set_roles(tokens, pieces[piece_idx], Role.SUFFIX)
+    if ambiguous_pick is not None:
+        piece, taken, declined = ambiguous_pick
+        ambiguities.append(PendingAmbiguity(
+            AmbiguityKind.SUFFIX_OR_FAMILY,
+            f"{tokens[piece[0]].text!r} written without periods is both "
+            f"a post-nominal and a surname; read as {taken} rather than "
+            f"{declined}",
+            tuple(piece)))
     # leading ambiguous particle read as a name (#121 surfaced)
     if name_pieces:
         head = pieces[name_pieces[0]]

nameparser/_pipeline/_classify.py

@@ -19,7 +19,10 @@
 import dataclasses
 
 from nameparser._lexicon import _normalize
-from nameparser._pipeline._state import ParseState, WorkToken
+from nameparser._pipeline._state import (
+    ParseState, PendingAmbiguity, WorkToken,
+)
+from nameparser._types import AmbiguityKind, Role
 from nameparser._pipeline._vocab import (
     is_initial, period_joined_vocab, suffix_as_written,
 )
@@ -73,4 +76,20 @@ def classify(state: ParseState) -> ParseState:
     tokens = tuple(
         dataclasses.replace(t, tags=_tags_for(t, state))
         for t in state.tokens)
-    return dataclasses.replace(state, tokens=tokens)
+    # Delimited content whose vocabulary cannot settle it: extract's
+    # escape sends an UNambiguous suffix straight through ("(MBA)" ->
+    # suffix) and keeps everything else as a nickname, so an AMBIGUOUS
+    # acronym in there was a coin the parser had to call. Reported here
+    # rather than at the escape itself, which runs before tokenize and
+    # so has no token index to point at.
+    ambiguities = list(state.ambiguities)
+    for i, token in enumerate(tokens):
+        if (token.role is Role.NICKNAME
+                and "vocab:suffix-ambiguous" in token.tags):
+            ambiguities.append(PendingAmbiguity(
+                AmbiguityKind.SUFFIX_OR_NICKNAME,
+                f"delimited {token.text!r} is also a post-nominal; read "
+                f"as a nickname rather than a suffix",
+                (i,)))
+    return dataclasses.replace(state, tokens=tokens,
+                               ambiguities=tuple(ambiguities))

nameparser/_types.py

@@ -231,9 +231,16 @@ class AmbiguityKind(StrEnum):
     #: two-word name under a non-default name_order). Not yet emitted;
     #: planned for 2.x.
     ORDER = "order"
-    #: Reserved: a trailing word reads plausibly as either a suffix or
-    #: a nickname. Not yet emitted; planned for 2.x.
+    #: Delimited content is an ambiguous suffix acronym, so it reads
+    #: plausibly as either a post-nominal or a nickname -- "JEFFREY
+    #: (JD) BRICKEN" keeps the nickname reading, where the
+    #: unambiguous "(MBA)" escapes to suffix on vocabulary alone.
     SUFFIX_OR_NICKNAME = "suffix-or-nickname"
+    #: An ambiguous suffix acronym written without periods, which is
+    #: also an ordinary surname -- "John Smith MA" reads MA as a
+    #: post-nominal because a family name remains, "Jack MA" reads it
+    #: as the family name because none would.
+    SUFFIX_OR_FAMILY = "suffix-or-family"
     #: A leading ambiguous particle was read as a given name -- "Van
     #: Johnson" parses given="Van", but "Van" is also a family-name
     #: particle in other names.

tests/v2/cases.py

@@ -87,23 +87,27 @@ def __post_init__(self) -> None:
                "them first (spans cannot reorder)"),
     Case("ambiguous_surname_acronyms", "Jack MA",
          {"given": "Jack", "family": "MA"},
+         ambiguities=("suffix-or-family",),
          notes="'ma'/'do' joined suffix_acronyms_ambiguous: with only "
                "two pieces, 'one of them is a credential' is the less "
                "likely reading, so the ambiguous acronym stays the "
                "family name (v1 parity via its reserve_last)"),
     Case("ambiguous_surname_acronym_with_suffix", "Jack MA Jr",
          {"given": "Jack", "family": "MA", "suffix": "Jr"},
+         ambiguities=("suffix-or-family",),
          notes="'Jr' peels first; 'MA' would then be the only piece "
                "left beside the given name, so it stays family"),
     Case("ambiguous_acronym_is_a_suffix_when_a_family_name_remains",
          "John Smith MA",
          {"given": "John", "family": "Smith", "suffix": "MA"},
+         ambiguities=("suffix-or-family",),
          notes="the other half of the same rule: three pieces means "
                "peeling 'MA' still leaves given+family, so the "
                "credential reading wins (v1 parity)"),
     Case("ambiguous_acronym_suffix_with_middle", "John Q Smith MA",
          {"given": "John", "middle": "Q", "family": "Smith",
-          "suffix": "MA"}),
+          "suffix": "MA"},
+         ambiguities=("suffix-or-family",)),
     Case("initial_shaped_not_conjunction", "john e. smith",
          {"given": "john", "middle": "e.", "family": "smith"},
          notes="v1 is_conjunction excludes initials at classify too"),
@@ -399,11 +403,14 @@ def __post_init__(self) -> None:
     Case("whitespace", "   ", {}),
     Case("bare_ambiguous_acronym", "John Ed",
          {"given": "John", "family": "Ed"},
-         notes="'ed' is an ambiguous acronym; bare form is a name (C1)"),
+         ambiguities=("suffix-or-family",),
+         notes="'ed' is an ambiguous acronym; bare form is a name (C1), "
+               "and the parse reports which reading it took"),
     Case("comma_ambiguous_acronym", "Smith, Ed",
          {"given": "Ed", "family": "Smith"}),
     Case("ambiguous_acronym_with_suffix", "John Ed III",
-         {"given": "John", "family": "Ed", "suffix": "III"}),
+         {"given": "John", "family": "Ed", "suffix": "III"},
+         ambiguities=("suffix-or-family",)),
     Case("phd_split", "John Ph. D.",
          {"given": "John", "suffix": "Ph. D."},
          notes="v1 fix_phd; healed via the stable 'joined' tag"),

tests/v2/test_contracts.py

@@ -11,10 +11,10 @@
     AmbiguityKind.PARTICLE_OR_GIVEN: "Van Johnson",
     AmbiguityKind.UNBALANCED_DELIMITER: 'Jon "Nick Smith',
     AmbiguityKind.COMMA_STRUCTURE: "Smith, John, Extra, Jr.",
+    AmbiguityKind.SUFFIX_OR_NICKNAME: "JEFFREY (JD) BRICKEN",
+    AmbiguityKind.SUFFIX_OR_FAMILY: "John Smith MA",
     # no emitter yet -- arrives with locale-pack order detection (2.x)
     AmbiguityKind.ORDER: None,
-    # no emitter yet -- arrives with suffix/nickname refinement (2.x)
-    AmbiguityKind.SUFFIX_OR_NICKNAME: None,
 }
 
 

tests/v2/test_parser.py

@@ -170,3 +170,44 @@ def test_phd_split_mid_name_is_a_suffix() -> None:
     assert pn.suffix == "Ph. D."
     assert pn.family == "Smith"
     assert pn.middle == ""
+
+
+def test_ambiguous_acronym_reports_the_reading_it_took() -> None:
+    # 'ma' is both a post-nominal and a surname, so whichever way the
+    # peel resolves it is a guess -- the same shape as the leading
+    # ambiguous particle that already reports PARTICLE_OR_GIVEN
+    took_suffix = parse("John Smith MA")
+    assert took_suffix.suffix == "MA"
+    assert [a.kind for a in took_suffix.ambiguities] == \
+        [AmbiguityKind.SUFFIX_OR_FAMILY]
+    assert [t.text for t in took_suffix.ambiguities[0].tokens] == ["MA"]
+
+    took_family = parse("Jack MA")
+    assert took_family.family == "MA"
+    assert [a.kind for a in took_family.ambiguities] == \
+        [AmbiguityKind.SUFFIX_OR_FAMILY]
+
+
+@pytest.mark.parametrize("text", [
+    "John Smith M.A.",                   # periods decide it; no guess
+    "Ma, Jack",                          # a comma fixes the family
+    "Joao da Silva do Amaral de Souza",  # 'do' mid-name, never at the peel
+    "John Smith PhD",                    # unambiguous vocabulary
+])
+def test_no_suffix_ambiguity_when_nothing_was_guessed(text: str) -> None:
+    assert [a for a in parse(text).ambiguities
+            if a.kind is AmbiguityKind.SUFFIX_OR_FAMILY] == []
+
+
+def test_delimited_ambiguous_acronym_reports_suffix_or_nickname() -> None:
+    # inside delimiters the competing readings are suffix and nickname:
+    # "(MBA)" is unambiguously a credential and escapes to suffix, while
+    # "(JD)" could be either, so it keeps the nickname reading -- a
+    # guess, and until now a silent one
+    n = parse("JEFFREY (JD) BRICKEN")
+    assert n.nickname == "JD"
+    assert [a.kind for a in n.ambiguities] == \
+        [AmbiguityKind.SUFFIX_OR_NICKNAME]
+    assert [t.text for t in n.ambiguities[0].tokens] == ["JD"]
+    # the unambiguous one decided on vocabulary, so it is not a guess
+    assert parse("Andrew Perkins (MBA)").ambiguities == ()