@reconcrap/people-network-memory 0.1.0

package/src/people_network_memory/application/normalization.py

@@ -0,0 +1,1441 @@
+"""Conservative source-text normalization for low-friction capture."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from datetime import date, timedelta
+
+from people_network_memory.domain.models import (
+    AttributedClaim,
+    DirectFact,
+    FollowUpTask,
+    MentionedPerson,
+    Participant,
+    PersonRef,
+    RelationshipAssertion,
+    SocialInteraction,
+)
+
+
+PLACEHOLDER_NAME = r"[Pp]erson\s+[A-Z]"
+LATIN_NAME = r"[A-Z][A-Za-z'-]+(?:\s+[A-Z][A-Za-z'-]+){0,2}"
+CJK_NAME = r"[\u4e00-\u9fff]{2,8}"
+CJK_ALIAS = r"[\u4e00-\u9fffA-Za-z0-9_-]{1,12}"
+PERSON = rf"(?:{PLACEHOLDER_NAME}|{LATIN_NAME}|{CJK_NAME})"
+
+EN_MET_RE = re.compile(
+    rf"\b(?i:met|spoke with|had coffee with|had dinner with|had lunch with|called)\s+"
+    rf"(?:(?i:another|a\s+different|different|new)\s+)?"
+    rf"(?P<person>{PERSON})(?=\s+(?i:at|today|yesterday|on|who|that)\b|[.,;]|$)",
+)
+EN_REMEMBER_RE = re.compile(rf"\b(?i:remember|add|save)\s+(?P<person>{PERSON})\b")
+EN_PLACE_RE = re.compile(
+    rf"\b(?i:met|spoke with|had coffee with|had dinner with|had lunch with|called)\s+{PERSON}"
+    rf"(?:\s+(?i:today|yesterday)|\s+(?i:on)\s+\d{{4}}-\d{{1,2}}-\d{{1,2}})?"
+    rf"\s+(?i:at)\s+(?P<place>[^.;,()]+)",
+)
+EN_ANOTHER_PLACE_RE = re.compile(
+    rf"\b(?i:met|spoke with|had coffee with|had dinner with|had lunch with|called)\s+"
+    rf"(?:(?i:another|a\s+different|different|new)\s+){PERSON}"
+    rf"(?:\s+(?i:today|yesterday)|\s+(?i:on)\s+\d{{4}}-\d{{1,2}}-\d{{1,2}})?"
+    rf"\s+(?i:at)\s+(?P<place>[^.;,()]+)",
+)
+EN_TOPIC_RE = re.compile(r"\b(?i:discussed|talked about|chatted about)\s+(?P<topic>[^.;]+)")
+EN_MENTION_RE = re.compile(
+    rf"\b(?P<speaker>{PERSON})\s+(?i:mentioned|said|told me)\s+(?P<target>{PERSON})\b",
+)
+EN_MET_KNOWS_RE = re.compile(
+    rf"\b(?i:met|spoke with|had coffee with|had dinner with|called)\s+"
+    rf"(?P<source>{PERSON})\s+(?i:who|that)\s+(?i:also\s+)?(?i:knows|knew)\s+(?P<target>{PERSON})\b",
+)
+EN_KNOWS_RE = re.compile(
+    rf"\b(?P<source>{PERSON})\s+(?i:also\s+)?(?i:knows|knew)\s+(?P<target>{PERSON})\b",
+)
+EN_FRIENDS_WITH_RE = re.compile(
+    rf"\b(?P<source>{PERSON})\s+(?i:is\s+)?(?i:friends?\s+with)\s+(?P<target>{PERSON})\b",
+)
+EN_WORKS_WITH_RE = re.compile(
+    rf"\b(?P<source>{PERSON})\s+(?i:works|worked|is\s+working)\s+(?i:with)\s+(?P<target>{PERSON})\b",
+)
+EN_INTRODUCED_ME_RE = re.compile(
+    rf"\b(?P<source>{PERSON})\s+(?i:introduced\s+me\s+to)\s+(?P<target>{PERSON})\b",
+)
+EN_PROMISE_RE = re.compile(r"\b(?i:(?:i\s+)?promised to)\s+(?P<task>[^.;]+)")
+EN_ASKED_ME_RE = re.compile(r"\b(?i:(?:he|she|they|[A-Z][A-Za-z'-]+)\s+asked\s+me\s+to)\s+(?P<task>[^.;]+)")
+ZH_PROMISE_RE = re.compile(r"(?:我)?(?:答应|承诺|说好|约好)(?P<task>[^。；;]+)")
+EN_WORK_RE = re.compile(
+    rf"\b(?P<person>{PERSON})\s+(?i:currently\s+)?(?i:works|is working|worked)\s+(?i:at|for)\s+"
+    r"(?P<organization>[^.;,]+?)(?:\s+(?i:as)\s+(?P<role>[^.;,]+))?(?=[.;,]|$)"
+)
+EN_STUDIED_RE = re.compile(
+    rf"\b(?P<person>{PERSON})\s+(?i:studied at|graduated from|went to)\s+(?P<school>[^.;,]+)"
+)
+EN_INTEREST_RE = re.compile(
+    rf"\b(?P<person>{PERSON})\s+(?i:likes|enjoys|is interested in|is into)\s+(?P<value>[^.;,]+)"
+)
+DEFAULT_WORK_RE = re.compile(r"\b(?i:works|is working|worked)\s+(?i:at|for)\s+(?P<organization>[^.;,]+)")
+DEFAULT_STUDIED_RE = re.compile(r"\b(?i:studied at|graduated from|went to)\s+(?P<school>[^.;,]+)")
+EMAIL_RE = re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b")
+PHONE_RE = re.compile(r"(?<!\d)(?:\+?\d[\d\s().-]{6,}\d)(?!\d)")
+ISO_DATE_RE = re.compile(r"\b(?P<year>20\d{2})[-/](?P<month>\d{1,2})[-/](?P<day>\d{1,2})\b")
+MONTH_DAY_RE = re.compile(
+    r"\b(?P<month>jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|"
+    r"jul(?:y)?|aug(?:ust)?|sep(?:tember)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)"
+    r"\s+(?P<day>\d{1,2})\b",
+    flags=re.IGNORECASE,
+)
+ZH_NEXT_WEEKDAY_RE = re.compile(
+    r"下(?:周|星期|礼拜)(?P<weekday>[一二三四五六日天])"
+)
+
+ZH_PARTICIPANT_RE = re.compile(
+    rf"(?:见了|认识了|遇到|碰到)(?P<person>{PERSON})"
+    r"(?=\s*[（(，,。.]|聊了|说|提到|也|和|他|她|其|在|喜欢|正在|可能|已经|$)"
+)
+ZH_CHAT_WITH_RE = re.compile(rf"和(?P<person>{PERSON})(?:聊了|聊天|见面)")
+ZH_ARRANGED_WITH_RE = re.compile(rf"和(?P<person>{PERSON})(?:约好|说好)")
+ZH_COMPLETED_SEND_TO_RE = re.compile(
+    rf"(?:已经|已|刚刚|刚)?(?:给|把)(?P<person>{PERSON})"
+    r"(?:发了|发送了|发过去了|分享了|转发了)"
+)
+ZH_REMEMBER_RE = re.compile(rf"(?:记住|记录|保存)(?P<person>{PERSON})")
+ZH_PLACE_RE = re.compile(r"在(?P<place>[^，。,.]+?)(?:又)?见了")
+ZH_TOPIC_RE = re.compile(r"聊了(?P<topic>[^，。,.]+)")
+ZH_FOCUS_TOPIC_RE = re.compile(
+    r"(?:重点看|重点关注|正在关注|也在关注|关注)(?P<topic>[^，。,.；;]+)"
+)
+ZH_ORG_FOCUS_CLAIM_RE = re.compile(
+    r"(?P<subject>[\u4e00-\u9fffA-Za-z0-9_-]{2,30}"
+    r"(?:公司|集团|科技|智能|机器人|资本|基金|大学|学院|实验室))"
+    r"(?P<time>上半年|下半年|今年|明年|后续|接下来|未来)"
+    r"(?:会|将|要)?"
+    r"(?P<focus>重点看|重点关注|关注)"
+    r"(?P<topic>[^，。,.；;]+)"
+)
+ZH_MENTION_RE = re.compile(rf"(?P<speaker>{PERSON})提到(?P<target>{PERSON})")
+ZH_DEFAULT_WORK_RE = re.compile(
+    r"(?:他|她|他们|她们|这个人|这人|此人)?在"
+    r"(?P<organization>[^，。,.；;]{2,30}?)(?:做|负责|从事|搞)"
+    r"(?P<role>[^，。,.；;]+)"
+)
+ZH_CONTACT_PREF_RE = re.compile(
+    r"(?:喜欢|偏好|倾向于|最好)(?:用|通过)?"
+    r"(?P<method>微信|短信|电话|邮件|邮箱|WhatsApp|飞书|钉钉)"
+    r"(?:联系|沟通|跟进)"
+)
+CONTACT_PREFERENCE_ONLY_RE = re.compile(
+    r"(?:之后|以后|后续|下次|以后有事)?\s*"
+    r"(?:最好|偏好|喜欢|倾向于)?\s*(?:用|通过)?\s*"
+    r"(?:微信|短信|电话|邮件|邮箱|whatsapp|飞书|钉钉)\s*"
+    r"(?:联系|沟通|跟进)",
+    flags=re.IGNORECASE,
+)
+CONCRETE_FOLLOW_UP_CUE_RE = re.compile(
+    r"(?:"
+    r"明天|后天|下周|周[一二三四五六日天]|星期[一二三四五六日天]|礼拜[一二三四五六日天]|"
+    r"\d{1,2}[月/.-]\d{1,2}|20\d{2}[-/]\d{1,2}[-/]\d{1,2}|"
+    r"答应|承诺|说好|约好|提醒我|需要我|让我|"
+    r"发|发送|推荐|介绍|引荐|安排|确认|准备|"
+    r"tomorrow|next\s+week|next\s+\w+day|by\s+\w+day|"
+    r"promised|asked\s+me\s+to|need\s+to|send|introduce|share|confirm|schedule"
+    r")",
+    flags=re.IGNORECASE,
+)
+ZH_ALIAS_CONTEXT = r"(?:[，。,.；;]|见了|认识了|遇到|碰到|记住|记录|保存|和)\s*"
+ZH_ALIAS_PAREN_RE = re.compile(
+    rf"{ZH_ALIAS_CONTEXT}(?P<canonical>{PERSON})\s*[（(](?P<alias>{CJK_ALIAS})[）)]"
+)
+ZH_ALIAS_START_PAREN_RE = re.compile(
+    rf"^(?P<canonical>{PERSON})\s*[（(](?P<alias>{CJK_ALIAS})[）)]"
+)
+ZH_ALIAS_PHRASE_RE = re.compile(
+    rf"{ZH_ALIAS_CONTEXT}(?P<canonical>{PERSON})"
+    rf"(?:又叫|也叫|昵称(?:是|叫)?|绰号(?:是|叫)?|外号(?:是|叫)?|花名(?:是|叫)?)"
+    rf"(?P<alias>{PERSON})"
+)
+ZH_ALIAS_START_PHRASE_RE = re.compile(
+    rf"^(?P<canonical>{PERSON})"
+    rf"(?:又叫|也叫|昵称(?:是|叫)?|绰号(?:是|叫)?|外号(?:是|叫)?|花名(?:是|叫)?)"
+    rf"(?P<alias>{PERSON})"
+)
+
+CJK_ALIAS_DESCRIPTORS = {
+    "前同事",
+    "同事",
+    "朋友",
+    "老同学",
+    "同学",
+    "校友",
+    "客户",
+    "投资人",
+    "创始人",
+    "合伙人",
+    "产品经理",
+    "工程师",
+}
+CJK_ALIAS_DESCRIPTOR_SUFFIXES = (
+    "经理",
+    "工程师",
+    "负责人",
+    "总监",
+    "同事",
+    "朋友",
+    "客户",
+    "投资人",
+    "创始人",
+    "合伙人",
+    "校友",
+    "同学",
+)
+BAD_PERSON_LABELS = {"i", "me", "my", "you", "he", "him", "his", "she", "her", "they", "them"}
+ORGANIZATION_LABEL_SUFFIXES = (
+    "公司",
+    "集团",
+    "科技",
+    "智能",
+    "机器人",
+    "资本",
+    "基金",
+    "大学",
+    "学院",
+    "实验室",
+)
+PHONE_PREDICATES = {"phone", "mobile", "telephone", "tel"}
+EMAIL_PREDICATES = {"email", "mail"}
+MONTHS = {
+    "jan": 1,
+    "january": 1,
+    "feb": 2,
+    "february": 2,
+    "mar": 3,
+    "march": 3,
+    "apr": 4,
+    "april": 4,
+    "may": 5,
+    "jun": 6,
+    "june": 6,
+    "jul": 7,
+    "july": 7,
+    "aug": 8,
+    "august": 8,
+    "sep": 9,
+    "september": 9,
+    "oct": 10,
+    "october": 10,
+    "nov": 11,
+    "november": 11,
+    "dec": 12,
+    "december": 12,
+}
+ZH_WEEKDAYS = {
+    "一": 0,
+    "二": 1,
+    "三": 2,
+    "四": 3,
+    "五": 4,
+    "六": 5,
+    "日": 6,
+    "天": 6,
+}
+
+
+def normalize_interaction(interaction: SocialInteraction) -> SocialInteraction:
+    """Fill obvious structure from source_text without inventing uncertain facts."""
+
+    source = interaction.source_text
+    explicit_aliases = _explicit_aliases(source)
+    participants = list(interaction.participants)
+    mentioned = list(interaction.mentioned_people)
+    topics = list(interaction.topics)
+    direct_facts = list(interaction.direct_facts)
+    attributed_claims = list(interaction.attributed_claims)
+    follow_ups = list(interaction.follow_ups)
+    relationships = list(interaction.relationships)
+    place = interaction.place
+
+    if not participants:
+        for label in _participant_labels(source):
+            _append_participant(participants, label)
+    for subject in _fact_subject_labels(source):
+        _append_participant(participants, subject)
+    for label in explicit_aliases:
+        _append_participant(participants, label)
+
+    if not place:
+        place = _first_match(source, [EN_ANOTHER_PLACE_RE, EN_PLACE_RE, ZH_PLACE_RE], "place")
+
+    topics = _normalize_topics(source, topics)
+
+    if not mentioned:
+        for speaker, target in _mention_pairs(source):
+            _append_participant(participants, speaker)
+            _append_mentioned(mentioned, target, mentioned_by=speaker)
+    for relationship_source, relationship_target, _ in _relationship_triples(source):
+        _append_mentioned(mentioned, relationship_target, mentioned_by=relationship_source)
+    if not attributed_claims:
+        for speaker, target in _mention_pairs(source):
+            attributed_claims.append(
+                AttributedClaim(
+                    speaker=PersonRef(label=speaker),
+                    subject=PersonRef(label=target),
+                    claim_text=_claim_sentence(source, speaker, target),
+                )
+            )
+    if not relationships:
+        for relationship_source, relationship_target, relationship_type in _relationship_triples(source):
+            relationships.append(
+                RelationshipAssertion(
+                    source=PersonRef(label=relationship_source),
+                    target=PersonRef(label=relationship_target),
+                    relationship_type=relationship_type,
+                )
+            )
+
+    direct_facts.extend(
+        _direct_facts(
+            source,
+            participants,
+            fallback_subject=_single_explicit_alias_ref(explicit_aliases),
+        )
+    )
+    for claim in _source_focus_claims(source, participants):
+        if not any(existing.claim_text == claim.claim_text for existing in attributed_claims):
+            attributed_claims.append(claim)
+
+    if not follow_ups:
+        for task in _follow_up_labels(source):
+            related = [
+                participant.person
+                for participant in participants
+                if _person_label_referenced_in_text(participant.person.label, task)
+            ]
+            follow_ups.append(FollowUpTask(description=f"Promised to {task}", related_people=related))
+
+    (
+        participants,
+        mentioned,
+        direct_facts,
+        attributed_claims,
+        follow_ups,
+        relationships,
+    ) = _sanitize_interaction_fields(
+        source=source,
+        occurred_at=interaction.occurred_at.date() if interaction.occurred_at else None,
+        place=place,
+        participants=participants,
+        mentioned=mentioned,
+        direct_facts=direct_facts,
+        attributed_claims=attributed_claims,
+        follow_ups=follow_ups,
+        relationships=relationships,
+    )
+
+    (
+        participants,
+        mentioned,
+        direct_facts,
+        attributed_claims,
+        follow_ups,
+        relationships,
+    ) = _canonicalize_shorthand_refs(
+        participants=participants,
+        mentioned=mentioned,
+        direct_facts=direct_facts,
+        attributed_claims=attributed_claims,
+        follow_ups=follow_ups,
+        relationships=relationships,
+        explicit_aliases=explicit_aliases,
+    )
+
+    return interaction.model_copy(
+        update={
+            "place": place,
+            "participants": participants,
+            "mentioned_people": mentioned,
+            "topics": topics,
+            "direct_facts": direct_facts,
+            "attributed_claims": attributed_claims,
+            "follow_ups": follow_ups,
+            "relationships": relationships,
+        }
+    )
+
+
+def _participant_labels(text: str) -> list[str]:
+    labels = [match.group("person").strip() for match in EN_MET_RE.finditer(text)]
+    labels.extend(match.group("person").strip() for match in EN_REMEMBER_RE.finditer(text))
+    labels.extend(match.group("person").strip() for match in ZH_PARTICIPANT_RE.finditer(text))
+    labels.extend(match.group("person").strip() for match in ZH_CHAT_WITH_RE.finditer(text))
+    labels.extend(match.group("person").strip() for match in ZH_ARRANGED_WITH_RE.finditer(text))
+    labels.extend(match.group("person").strip() for match in ZH_COMPLETED_SEND_TO_RE.finditer(text))
+    labels.extend(match.group("person").strip() for match in ZH_REMEMBER_RE.finditer(text))
+    return _unique_labels(labels)
+
+
+def _fact_subject_labels(text: str) -> list[str]:
+    labels: list[str] = []
+    for pattern in [EN_WORK_RE, EN_STUDIED_RE, EN_INTEREST_RE]:
+        labels.extend(match.group("person").strip() for match in pattern.finditer(text))
+    return _unique_labels(label for label in labels if _is_probable_person(label))
+
+
+def _topic_labels(text: str) -> list[str]:
+    labels = [match.group("topic").strip() for match in EN_TOPIC_RE.finditer(text)]
+    labels.extend(match.group("topic").strip() for match in ZH_TOPIC_RE.finditer(text))
+    labels.extend(match.group("topic").strip() for match in ZH_FOCUS_TOPIC_RE.finditer(text))
+    return _unique_labels(labels)
+
+
+def _normalize_topics(source: str, topics: list[str]) -> list[str]:
+    normalized: list[str] = []
+    for topic in topics:
+        cleaned = _clean_topic_label(topic)
+        if cleaned and not _is_noise_topic(cleaned) and cleaned not in normalized:
+            normalized.append(cleaned)
+    for label in _topic_labels(source):
+        cleaned = _clean_topic_label(label)
+        if cleaned and not _is_noise_topic(cleaned) and cleaned not in normalized:
+            normalized.append(cleaned)
+    return normalized
+
+
+def _clean_topic_label(value: str) -> str:
+    value = value.strip(" \t\r\n,.;:，。！？!?\"'")
+    value = re.sub(r"^(?:他|她|他们|她们|这个人|这人|现在|也|在|会|将|要)\s*", "", value)
+    return value.strip(" \t\r\n,.;:，。！？!?\"'")
+
+
+def _is_noise_topic(value: str) -> bool:
+    value = value.strip()
+    if not value:
+        return True
+    if value in {"今天", "昨天", "刚刚", "早些时候", "上午", "下午", "晚上"}:
+        return True
+    return bool(
+        re.fullmatch(
+            r"(?:半|一|二|三|四|五|六|七|八|九|十|两|\d+)+"
+            r"(?:分钟|小时|天|周|个月|年)",
+            value,
+        )
+    )
+
+
+def _source_focus_claims(
+    source: str, participants: list[Participant]
+) -> list[AttributedClaim]:
+    speaker = _default_subject(participants)
+    if not speaker:
+        return []
+    claims: list[AttributedClaim] = []
+    for match in ZH_ORG_FOCUS_CLAIM_RE.finditer(source):
+        subject = _clean_focus_subject(match.group("subject"))
+        topic = _clean_topic_label(match.group("topic"))
+        if not topic or _is_noise_topic(topic):
+            continue
+        claim_text = match.group(0).strip()
+        for prefix in ("他说", "她说", "他们说", "她们说", "表示", "提到"):
+            if claim_text.startswith(prefix):
+                claim_text = claim_text[len(prefix) :].strip()
+                break
+        claims.append(
+            AttributedClaim(
+                speaker=speaker,
+                subject=PersonRef(label=subject),
+                claim_text=claim_text,
+                claim_type="business_focus",
+            )
+        )
+    return claims
+
+
+def _clean_focus_subject(value: str) -> str:
+    value = value.strip()
+    for prefix in ("他说", "她说", "他们说", "她们说", "表示", "提到"):
+        if value.startswith(prefix):
+            return value[len(prefix) :].strip()
+    return value
+
+
+def _mention_pairs(text: str) -> list[tuple[str, str]]:
+    pairs = [
+        (match.group("speaker").strip(), match.group("target").strip())
+        for match in EN_MENTION_RE.finditer(text)
+    ]
+    pairs.extend(
+        (match.group("speaker").strip(), match.group("target").strip())
+        for match in ZH_MENTION_RE.finditer(text)
+    )
+    return [
+        pair
+        for pair in _unique_pairs(pairs)
+        if _is_probable_person(pair[0]) and _is_probable_person(pair[1])
+    ]
+
+
+def _relationship_triples(text: str) -> list[tuple[str, str, str]]:
+    triples: list[tuple[str, str, str]] = []
+    relationship_patterns = [
+        (EN_MET_KNOWS_RE, "knows"),
+        (EN_KNOWS_RE, "knows"),
+        (EN_FRIENDS_WITH_RE, "friends_with"),
+        (EN_WORKS_WITH_RE, "works_with"),
+        (EN_INTRODUCED_ME_RE, "introduced_by"),
+    ]
+    for pattern, relationship_type in relationship_patterns:
+        triples.extend(
+            (
+                match.group("source").strip(),
+                match.group("target").strip(),
+                relationship_type,
+            )
+            for match in pattern.finditer(text)
+        )
+    return [
+        triple
+        for triple in _unique_triples(triples)
+        if _is_probable_person(triple[0]) and _is_probable_person(triple[1])
+    ]
+
+
+def _direct_facts(
+    text: str,
+    participants: list[Participant],
+    *,
+    fallback_subject: PersonRef | None = None,
+) -> list[DirectFact]:
+    facts: list[DirectFact] = []
+    for match in EN_WORK_RE.finditer(text):
+        subject = PersonRef(label=match.group("person").strip())
+        organization = match.group("organization").strip()
+        facts.append(
+            DirectFact(
+                subject=subject,
+                predicate="works_at",
+                value=organization,
+                metadata=_optional_metadata(role=match.group("role")),
+            )
+        )
+    for match in EN_STUDIED_RE.finditer(text):
+        facts.append(
+            DirectFact(
+                subject=PersonRef(label=match.group("person").strip()),
+                predicate="studied_at",
+                value=match.group("school").strip(),
+            )
+        )
+    for match in EN_INTEREST_RE.finditer(text):
+        facts.append(
+            DirectFact(
+                subject=PersonRef(label=match.group("person").strip()),
+                predicate="interest",
+                value=match.group("value").strip(),
+            )
+        )
+    subject = _default_subject(participants) or fallback_subject
+    if subject:
+        for match in DEFAULT_WORK_RE.finditer(text):
+            facts.append(
+                DirectFact(
+                    subject=subject,
+                    predicate="works_at",
+                    value=match.group("organization").strip(),
+                )
+            )
+        for match in DEFAULT_STUDIED_RE.finditer(text):
+            facts.append(
+                DirectFact(
+                    subject=subject,
+                    predicate="studied_at",
+                    value=match.group("school").strip(),
+                )
+            )
+        for match in ZH_DEFAULT_WORK_RE.finditer(text):
+            organization = match.group("organization").strip()
+            role = match.group("role").strip()
+            facts.append(
+                DirectFact(
+                    subject=subject,
+                    predicate="works_at",
+                    value=organization,
+                    metadata=_optional_metadata(role=role),
+                )
+            )
+        for match in ZH_CONTACT_PREF_RE.finditer(text):
+            facts.append(
+                DirectFact(
+                    subject=subject,
+                    predicate="preference",
+                    value=f"{match.group('method').strip()}联系",
+                )
+            )
+        for email in EMAIL_RE.findall(text):
+            facts.append(DirectFact(subject=subject, predicate="email", value=email))
+        for phone in PHONE_RE.findall(text):
+            facts.append(DirectFact(subject=subject, predicate="phone", value=phone.strip()))
+    return facts
+
+
+def _follow_up_labels(text: str) -> list[str]:
+    labels = [match.group("task").strip() for match in EN_PROMISE_RE.finditer(text)]
+    labels.extend(match.group("task").strip() for match in EN_ASKED_ME_RE.finditer(text))
+    labels.extend(match.group("task").strip() for match in ZH_PROMISE_RE.finditer(text))
+    return _unique_labels(label.strip(" \t\r\n,.;:，。！？!?\"'") for label in labels)
+
+
+def _append_participant(participants: list[Participant], label: str) -> None:
+    label = _clean_person_label(label)
+    if not _is_probable_person(label):
+        return
+    for index, participant in enumerate(participants):
+        existing = participant.person.label
+        if existing.lower() == label.lower():
+            return
+        if _same_person_label(existing, label):
+            if _is_full_latin_name(label) and not _is_full_latin_name(existing):
+                participants[index] = participant.model_copy(
+                    update={"person": participant.person.model_copy(update={"label": label})}
+                )
+            return
+    participants.append(Participant(person=PersonRef(label=label)))
+
+
+def _append_mentioned(
+    mentioned: list[MentionedPerson], label: str, *, mentioned_by: str | None = None
+) -> None:
+    label = _clean_person_label(label)
+    mentioned_by = _clean_person_label(mentioned_by) if mentioned_by else None
+    if not _is_probable_person(label):
+        return
+    if any(item.person.label == label for item in mentioned):
+        return
+    mentioned.append(
+        MentionedPerson(
+            person=PersonRef(label=label),
+            mentioned_by=PersonRef(label=mentioned_by) if mentioned_by else None,
+        )
+    )
+
+
+def _first_match(text: str, patterns: list[re.Pattern[str]], group: str) -> str | None:
+    for pattern in patterns:
+        match = pattern.search(text)
+        if match:
+            value = match.group(group).strip()
+            if group == "place":
+                value = _clean_place_label(value)
+            return value or None
+    return None
+
+
+def _clean_place_label(value: str) -> str:
+    return re.sub(
+        r"\s+\b(?:this afternoon|this morning|this evening|today|yesterday|tonight)\b.*$",
+        "",
+        value.strip(),
+        flags=re.IGNORECASE,
+    ).strip()
+
+
+def _claim_sentence(text: str, speaker: str, target: str) -> str:
+    for sentence in re.split(r"(?<=[.;。])\s*", text):
+        if speaker in sentence and target in sentence:
+            return sentence.strip()
+    return f"{speaker} mentioned {target}."
+
+
+def _sanitize_interaction_fields(
+    *,
+    source: str,
+    occurred_at: date | None,
+    place: str | None,
+    participants: list[Participant],
+    mentioned: list[MentionedPerson],
+    direct_facts: list[DirectFact],
+    attributed_claims: list[AttributedClaim],
+    follow_ups: list[FollowUpTask],
+    relationships: list[RelationshipAssertion],
+) -> tuple[
+    list[Participant],
+    list[MentionedPerson],
+    list[DirectFact],
+    list[AttributedClaim],
+    list[FollowUpTask],
+    list[RelationshipAssertion],
+]:
+    cleaned_participants: list[Participant] = []
+    for participant in participants:
+        person = _clean_ref(participant.person, place=place)
+        if person:
+            cleaned_participants.append(participant.model_copy(update={"person": person}))
+    cleaned_participants = _dedupe_participants(cleaned_participants)
+    default_ref = _default_subject(cleaned_participants)
+
+    cleaned_mentioned: list[MentionedPerson] = []
+    for item in mentioned:
+        person = _clean_ref(item.person, place=place)
+        if not person:
+            continue
+        mentioned_by = _clean_ref(item.mentioned_by, place=place) if item.mentioned_by else None
+        cleaned_mentioned.append(
+            item.model_copy(update={"person": person, "mentioned_by": mentioned_by})
+        )
+    cleaned_mentioned = _dedupe_mentioned(cleaned_mentioned)
+
+    cleaned_facts: list[DirectFact] = []
+    for fact in direct_facts:
+        subject = _clean_ref(fact.subject, place=place)
+        if subject is None and _is_bad_person_label(fact.subject.label) and default_ref:
+            subject = default_ref
+        if subject is None:
+            continue
+        normalized = fact.model_copy(update={"subject": subject})
+        if _valid_direct_fact(normalized, source=source):
+            cleaned_facts.append(normalized)
+    cleaned_facts = _dedupe_model_items(cleaned_facts)
+
+    cleaned_claims: list[AttributedClaim] = []
+    for claim in attributed_claims:
+        speaker = _clean_ref(claim.speaker, place=place) if claim.speaker else None
+        subject = _clean_ref(claim.subject, place=place) if claim.subject else None
+        if speaker is None and claim.speaker and _is_bad_person_label(claim.speaker.label):
+            speaker = default_ref
+        if subject is None and claim.subject and _is_bad_person_label(claim.subject.label):
+            subject = default_ref
+        if not speaker and not subject:
+            continue
+        if speaker and subject and _same_person_label(speaker.label, subject.label):
+            if _looks_like_follow_up_claim(claim.claim_text):
+                continue
+        cleaned_claims.append(claim.model_copy(update={"speaker": speaker, "subject": subject}))
+    cleaned_claims = _dedupe_model_items(cleaned_claims)
+
+    cleaned_follow_ups: list[FollowUpTask] = []
+    for follow_up in follow_ups:
+        if _looks_like_contact_preference_only_follow_up(follow_up.description):
+            continue
+        related = [
+            ref
+            for ref in (
+                _clean_ref(ref, place=place) for ref in follow_up.related_people
+            )
+            if ref is not None
+        ]
+        if not related and default_ref:
+            related = [default_ref]
+        due_at = follow_up.due_at or _date_hint_from_text(
+            follow_up.description,
+            source,
+            reference_date=occurred_at,
+        )
+        cleaned_follow_ups.append(
+            follow_up.model_copy(update={"related_people": related, "due_at": due_at})
+        )
+    cleaned_follow_ups = _dedupe_follow_ups(cleaned_follow_ups)
+
+    cleaned_relationships: list[RelationshipAssertion] = []
+    for relationship in relationships:
+        source_ref = _clean_ref(relationship.source, place=place)
+        target_ref = _clean_ref(relationship.target, place=place)
+        if not source_ref or not target_ref:
+            continue
+        cleaned_relationships.append(
+            relationship.model_copy(update={"source": source_ref, "target": target_ref})
+        )
+    cleaned_relationships = _dedupe_model_items(cleaned_relationships)
+
+    return (
+        cleaned_participants,
+        cleaned_mentioned,
+        cleaned_facts,
+        cleaned_claims,
+        cleaned_follow_ups,
+        cleaned_relationships,
+    )
+
+
+def _clean_ref(ref: PersonRef | None, *, place: str | None) -> PersonRef | None:
+    if ref is None:
+        return None
+    label = _clean_person_label(ref.label)
+    aliases = [
+        alias
+        for alias in (_clean_person_label(alias) for alias in ref.aliases)
+        if alias and alias != label and not _is_date_like(alias)
+    ]
+    updated = ref.model_copy(update={"label": label, "aliases": _unique_labels(aliases)})
+    if not _valid_person_ref(updated, place=place):
+        return None
+    return updated
+
+
+def _clean_person_label(label: str | None) -> str:
+    label = (label or "").strip(" \t\r\n,.;:，。！？!?\"'")
+    if not label:
+        return ""
+    label = re.sub(
+        r"^(?:另一个|另外一个|另一位|另位|不同的|新的)\s*",
+        "",
+        label,
+    ).strip()
+    label = re.sub(
+        r"^(?:this|that|another|a\s+different|different|new)\s+",
+        "",
+        label,
+        flags=re.IGNORECASE,
+    ).strip()
+    if re.fullmatch(r"[\u4e00-\u9fff]+", label):
+        for marker in ["也", "正在", "可能", "已经"]:
+            if marker in label:
+                prefix = label.split(marker, 1)[0]
+                if 2 <= len(prefix) <= 4:
+                    return prefix
+    return label
+
+
+def _valid_person_ref(ref: PersonRef, *, place: str | None) -> bool:
+    if _is_bad_person_label(ref.label):
+        return False
+    if _looks_like_organization_label(ref.label):
+        return False
+    if _is_date_like(ref.label):
+        return False
+    if place and ref.label.strip().casefold() == place.strip().casefold():
+        return False
+    return _is_probable_person(ref.label)
+
+
+def _is_bad_person_label(label: str) -> bool:
+    return label.strip().casefold() in BAD_PERSON_LABELS
+
+
+def _looks_like_organization_label(label: str) -> bool:
+    stripped = label.strip()
+    if stripped.startswith("测试"):
+        return False
+    return any(stripped.endswith(suffix) for suffix in ORGANIZATION_LABEL_SUFFIXES)
+
+
+def _is_date_like(value: str) -> bool:
+    return bool(ISO_DATE_RE.fullmatch(value.strip()))
+
+
+def _valid_direct_fact(fact: DirectFact, *, source: str = "") -> bool:
+    predicate = fact.predicate.strip().casefold()
+    value = fact.value.strip()
+    if predicate in PHONE_PREDICATES:
+        return bool(PHONE_RE.fullmatch(value)) and not _is_date_like(value)
+    if predicate in EMAIL_PREDICATES:
+        return bool(EMAIL_RE.fullmatch(value))
+    if predicate in {"works_at", "worked_at", "work", "current_job"}:
+        if _looks_like_contrast_only_work_fact(source, fact.subject.label, value):
+            return False
+    return bool(value)
+
+
+def _looks_like_contrast_only_work_fact(source: str, person_label: str, organization: str) -> bool:
+    if not source or not person_label or not organization:
+        return False
+    person = re.escape(person_label.strip())
+    org = re.escape(organization.strip())
+    patterns = [
+        rf"和{org}(?:的|那个|那位)?{person}[^。；;,.，]*(?:不是同一个人|不是一个人|不同的人)",
+        rf"{org}(?:的|那个|那位)?{person}[^。；;,.，]*(?:不是同一个人|不是一个人|不同的人)",
+        rf"(?:不是同一个人|不是一个人|不同的人)[^。；;,.，]*{org}(?:的|那个|那位)?{person}",
+    ]
+    return any(re.search(pattern, source) for pattern in patterns)
+
+
+def _looks_like_follow_up_claim(text: str) -> bool:
+    lowered = text.casefold()
+    return any(
+        phrase in lowered
+        for phrase in [
+            "asked me to",
+            "asked us to",
+            "reminded me to",
+            "promised to",
+            "答应",
+            "提醒我",
+        ]
+    )
+
+
+def _looks_like_contact_preference_only_follow_up(text: str) -> bool:
+    normalized = " ".join(text.casefold().split())
+    if not CONTACT_PREFERENCE_ONLY_RE.search(normalized):
+        return False
+    without_contact_phrase = CONTACT_PREFERENCE_ONLY_RE.sub("", normalized).strip()
+    without_contact_phrase = re.sub(r"^[,，。；;\s]+|[,，。；;\s]+$", "", without_contact_phrase)
+    if CONCRETE_FOLLOW_UP_CUE_RE.search(without_contact_phrase):
+        return False
+    return True
+
+
+def _dedupe_mentioned(items: list[MentionedPerson]) -> list[MentionedPerson]:
+    by_person: dict[str, MentionedPerson] = {}
+    for item in items:
+        key = item.person.label.casefold()
+        existing = by_person.get(key)
+        if existing is None or _mentioned_quality(item) > _mentioned_quality(existing):
+            by_person[key] = item
+    return list(by_person.values())
+
+
+def _mentioned_quality(item: MentionedPerson) -> int:
+    return int(item.mentioned_by is not None) + int(bool(item.context))
+
+
+def _dedupe_follow_ups(items: list[FollowUpTask]) -> list[FollowUpTask]:
+    result: list[FollowUpTask] = []
+    for item in items:
+        existing_index = next(
+            (
+                index
+                for index, existing in enumerate(result)
+                if _similar_follow_up(existing.description, item.description)
+            ),
+            None,
+        )
+        if existing_index is None:
+            result.append(item)
+            continue
+        existing = result[existing_index]
+        replacement = item if _follow_up_quality(item) > _follow_up_quality(existing) else existing
+        result[existing_index] = replacement
+    return result
+
+
+def _similar_follow_up(left: str, right: str) -> bool:
+    left_key = _follow_up_key(left)
+    right_key = _follow_up_key(right)
+    if left_key == right_key:
+        return True
+    return left_key in right_key or right_key in left_key
+
+
+def _follow_up_quality(item: FollowUpTask) -> int:
+    return len(item.description) + (25 if item.due_at else 0) + (5 * len(item.related_people))
+
+
+def _follow_up_key(value: str) -> str:
+    return re.sub(r"\s+", " ", value.casefold().replace("promised to ", "")).strip()
+
+
+def _dedupe_model_items(items: list):
+    result: list = []
+    seen: set[str] = set()
+    for item in items:
+        key = item.model_dump_json()
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(item)
+    return result
+
+
+def _dedupe_direct_facts(items: list[DirectFact]) -> list[DirectFact]:
+    result: list[DirectFact] = []
+    seen: dict[tuple[str, str, str], int] = {}
+    for item in items:
+        key = (
+            item.subject.label.casefold(),
+            item.predicate.casefold(),
+            item.value.casefold(),
+        )
+        if key in seen:
+            existing_index = seen[key]
+            existing = result[existing_index]
+            if not existing.metadata and item.metadata:
+                result[existing_index] = item
+            continue
+        seen[key] = len(result)
+        result.append(item)
+    return result
+
+
+def _date_hint_from_text(
+    text: str, source: str, *, reference_date: date | None = None
+) -> date | None:
+    match = ISO_DATE_RE.search(text)
+    if match:
+        return _safe_date(
+            int(match.group("year")),
+            int(match.group("month")),
+            int(match.group("day")),
+        )
+    source_date = _first_source_date(source) or reference_date or date.today()
+    month_match = MONTH_DAY_RE.search(text)
+    if month_match and source_date:
+        month = MONTHS[month_match.group("month").casefold()]
+        return _safe_date(source_date.year, month, int(month_match.group("day")))
+    zh_weekday_match = ZH_NEXT_WEEKDAY_RE.search(text)
+    if zh_weekday_match and source_date:
+        target_weekday = ZH_WEEKDAYS[zh_weekday_match.group("weekday")]
+        days_until_next_week = 7 - source_date.weekday() + target_weekday
+        return source_date + timedelta(days=days_until_next_week)
+    if "tomorrow" in text.casefold() and source_date:
+        return source_date + timedelta(days=1)
+    return None
+
+
+def _first_source_date(source: str) -> date | None:
+    match = ISO_DATE_RE.search(source)
+    if not match:
+        return None
+    return _safe_date(
+        int(match.group("year")),
+        int(match.group("month")),
+        int(match.group("day")),
+    )
+
+
+def _safe_date(year: int, month: int, day: int) -> date | None:
+    try:
+        return date(year, month, day)
+    except ValueError:
+        return None
+
+
+def _canonicalize_shorthand_refs(
+    *,
+    participants: list[Participant],
+    mentioned: list[MentionedPerson],
+    direct_facts: list[DirectFact],
+    attributed_claims: list[AttributedClaim],
+    follow_ups: list[FollowUpTask],
+    relationships: list[RelationshipAssertion],
+    explicit_aliases: dict[str, list[str]] | None = None,
+) -> tuple[
+    list[Participant],
+    list[MentionedPerson],
+    list[DirectFact],
+    list[AttributedClaim],
+    list[FollowUpTask],
+    list[RelationshipAssertion],
+]:
+    explicit_aliases = explicit_aliases or {}
+    alias_map = _participant_shorthand_map(participants)
+    alias_map.update(_explicit_alias_map(explicit_aliases, participants))
+    if not alias_map and not explicit_aliases:
+        return participants, mentioned, direct_facts, attributed_claims, follow_ups, relationships
+
+    canonical_participants = _dedupe_participants(
+        [
+            participant.model_copy(
+                update={
+                    "person": _canonicalize_ref(
+                        participant.person,
+                        alias_map,
+                        explicit_aliases,
+                    )
+                }
+            )
+            for participant in participants
+        ]
+    )
+    return (
+        canonical_participants,
+        [
+            item.model_copy(
+                update={
+                    "person": _canonicalize_ref(item.person, alias_map, explicit_aliases),
+                    "mentioned_by": (
+                        _canonicalize_ref(
+                            item.mentioned_by,
+                            alias_map,
+                            explicit_aliases,
+                        )
+                        if item.mentioned_by
+                        else None
+                    ),
+                }
+            )
+            for item in mentioned
+        ],
+        _dedupe_direct_facts([
+            fact.model_copy(
+                update={
+                    "subject": _canonicalize_ref(
+                        fact.subject,
+                        alias_map,
+                        explicit_aliases,
+                    )
+                }
+            )
+            for fact in direct_facts
+        ]),
+        [
+            claim.model_copy(
+                update={
+                    "speaker": (
+                        _canonicalize_ref(
+                            claim.speaker,
+                            alias_map,
+                            explicit_aliases,
+                        )
+                        if claim.speaker
+                        else None
+                    ),
+                    "subject": (
+                        _canonicalize_ref(
+                            claim.subject,
+                            alias_map,
+                            explicit_aliases,
+                        )
+                        if claim.subject
+                        else None
+                    ),
+                }
+            )
+            for claim in attributed_claims
+        ],
+        [
+            follow_up.model_copy(
+                update={
+                    "related_people": [
+                        _canonicalize_ref(ref, alias_map, explicit_aliases)
+                        for ref in follow_up.related_people
+                    ]
+                }
+            )
+            for follow_up in follow_ups
+        ],
+        [
+            relationship.model_copy(
+                update={
+                    "source": _canonicalize_ref(
+                        relationship.source,
+                        alias_map,
+                        explicit_aliases,
+                    ),
+                    "target": _canonicalize_ref(
+                        relationship.target,
+                        alias_map,
+                        explicit_aliases,
+                    ),
+                }
+            )
+            for relationship in relationships
+        ],
+    )
+
+
+def _explicit_aliases(text: str) -> dict[str, list[str]]:
+    aliases: dict[str, list[str]] = {}
+    for pattern in [ZH_ALIAS_PAREN_RE, ZH_ALIAS_START_PAREN_RE]:
+        for match in pattern.finditer(text):
+            canonical = match.group("canonical").strip()
+            alias = match.group("alias").strip()
+            _add_explicit_alias(aliases, canonical, alias)
+    for pattern in [ZH_ALIAS_PHRASE_RE, ZH_ALIAS_START_PHRASE_RE]:
+        for match in pattern.finditer(text):
+            canonical = match.group("canonical").strip()
+            alias = match.group("alias").strip()
+            _add_explicit_alias(aliases, canonical, alias)
+    return aliases
+
+
+def _single_explicit_alias_ref(explicit_aliases: dict[str, list[str]]) -> PersonRef | None:
+    if len(explicit_aliases) != 1:
+        return None
+    canonical, aliases = next(iter(explicit_aliases.items()))
+    return PersonRef(label=canonical, aliases=aliases)
+
+
+def _add_explicit_alias(aliases: dict[str, list[str]], canonical: str, alias: str) -> None:
+    if _looks_like_cjk_context_fragment(canonical):
+        return
+    if not _is_probable_person(canonical):
+        return
+    if not _is_probable_alias(alias):
+        return
+    if _is_date_like(alias):
+        return
+    if canonical.casefold() == alias.casefold():
+        return
+    items = aliases.setdefault(canonical, [])
+    if alias not in items:
+        items.append(alias)
+
+
+def _looks_like_cjk_context_fragment(label: str) -> bool:
+    if not re.fullmatch(CJK_NAME, label):
+        return False
+    if label.startswith(("今天", "昨天", "前天", "今晚", "上午", "下午", "晚上")):
+        return True
+    return any(marker in label for marker in ["见了", "认识了", "遇到", "碰到", "记住", "记录", "保存"])
+
+
+def _is_probable_alias(alias: str) -> bool:
+    alias = alias.strip()
+    if not alias or alias in CJK_ALIAS_DESCRIPTORS:
+        return False
+    if alias.endswith(CJK_ALIAS_DESCRIPTOR_SUFFIXES):
+        return False
+    return bool(re.fullmatch(CJK_ALIAS, alias))
+
+
+def _explicit_alias_map(
+    explicit_aliases: dict[str, list[str]],
+    participants: list[Participant],
+) -> dict[str, str]:
+    canonical_by_alias: dict[str, str | None] = {}
+    explicit_lookup: dict[str, str | None] = {}
+    for canonical, aliases in explicit_aliases.items():
+        _remember_alias_candidate(explicit_lookup, canonical, canonical)
+        for alias in aliases:
+            _remember_alias_candidate(canonical_by_alias, alias, canonical)
+            _remember_alias_candidate(explicit_lookup, alias, canonical)
+    for participant in participants:
+        ref = participant.person
+        if ref.person_id or ref.email or ref.phone or ref.company_hint:
+            continue
+        label_key = ref.label.strip().casefold()
+        if not label_key:
+            continue
+        explicit_canonical = _explicit_canonical_for_ref(ref, explicit_lookup, explicit_aliases)
+        if explicit_canonical and explicit_canonical != ref.label:
+            _remember_alias_candidate(canonical_by_alias, ref.label, explicit_canonical)
+            for alias in ref.aliases:
+                _remember_alias_candidate(canonical_by_alias, alias, explicit_canonical)
+        for alias in ref.aliases:
+            canonical = canonical_by_alias.get(alias.strip().casefold())
+            if not canonical or canonical == ref.label:
+                continue
+            _remember_alias_candidate(canonical_by_alias, ref.label, canonical)
+    return {
+        alias: canonical
+        for alias, canonical in canonical_by_alias.items()
+        if canonical is not None and not _has_distinct_alias_ref(participants, alias, canonical)
+    }
+
+
+def _remember_alias_candidate(
+    mapping: dict[str, str | None], alias: str, canonical: str
+) -> None:
+    alias_key = alias.strip().casefold()
+    if not alias_key:
+        return
+    if alias_key not in mapping:
+        mapping[alias_key] = canonical
+    elif mapping[alias_key] != canonical:
+        mapping[alias_key] = None
+
+
+def _explicit_canonical_for_ref(
+    ref: PersonRef,
+    explicit_lookup: dict[str, str | None],
+    explicit_aliases: dict[str, list[str]],
+) -> str | None:
+    labels = [ref.label, *ref.aliases]
+    matches = {
+        canonical
+        for label in labels
+        for canonical in [explicit_lookup.get(label.strip().casefold())]
+        if canonical is not None
+    }
+    for canonical in explicit_aliases:
+        if _same_test_prefixed_cjk_name(canonical, ref.label):
+            matches.add(canonical)
+    return next(iter(matches)) if len(matches) == 1 else None
+
+
+def _same_test_prefixed_cjk_name(canonical: str, label: str) -> bool:
+    canonical = canonical.strip()
+    label = label.strip()
+    if not canonical.startswith("测试"):
+        return False
+    stripped = canonical.removeprefix("测试")
+    return bool(stripped and label == stripped and re.fullmatch(CJK_NAME, stripped))
+
+
+def _participant_shorthand_map(participants: list[Participant]) -> dict[str, str]:
+    canonical_by_alias: dict[str, str | None] = {}
+    for participant in participants:
+        label = participant.person.label.strip()
+        for alias in participant.person.aliases:
+            alias_key = alias.strip().casefold()
+            if not alias_key or alias_key == label.casefold():
+                continue
+            if alias_key not in canonical_by_alias:
+                canonical_by_alias[alias_key] = label
+            elif canonical_by_alias[alias_key] != label:
+                canonical_by_alias[alias_key] = None
+        if not _is_full_latin_name(label):
+            continue
+        for alias in _latin_name_aliases(label):
+            if alias not in canonical_by_alias:
+                canonical_by_alias[alias] = label
+            elif canonical_by_alias[alias] != label:
+                canonical_by_alias[alias] = None
+    return {
+        alias: full
+        for alias, full in canonical_by_alias.items()
+        if full is not None and not _has_distinct_alias_ref(participants, alias, full)
+    }
+
+
+def _has_distinct_alias_ref(
+    participants: list[Participant], alias: str, full_name: str
+) -> bool:
+    for participant in participants:
+        ref = participant.person
+        label = ref.label.strip()
+        if label.lower() != alias:
+            continue
+        if ref.person_id or ref.email or ref.phone or ref.company_hint:
+            return True
+        if label.lower() == full_name.lower():
+            return True
+    return False
+
+
+def _canonicalize_ref(
+    ref: PersonRef,
+    alias_map: dict[str, str],
+    explicit_aliases: dict[str, list[str]],
+) -> PersonRef:
+    label = ref.label.strip()
+    explicit_canonical = _explicit_canonical_label(label, explicit_aliases)
+    canonical = (
+        label
+        if (ref.person_id or ref.email or ref.phone)
+        else explicit_canonical or alias_map.get(label.casefold())
+    )
+    if not canonical and not (ref.person_id or ref.email or ref.phone):
+        for alias in ref.aliases:
+            canonical = alias_map.get(alias.strip().casefold())
+            if canonical:
+                break
+    if not canonical:
+        canonical = label
+    aliases = [alias for alias in ref.aliases if alias != canonical]
+    if label != canonical and label not in aliases:
+        aliases.append(label)
+    for alias in explicit_aliases.get(canonical, []):
+        if alias != canonical and alias not in aliases:
+            aliases.append(alias)
+    if canonical == ref.label and aliases == ref.aliases:
+        return ref
+    return ref.model_copy(update={"label": canonical, "aliases": aliases})
+
+
+def _explicit_canonical_label(
+    label: str, explicit_aliases: dict[str, list[str]]
+) -> str | None:
+    label_key = label.strip().casefold()
+    for canonical in explicit_aliases:
+        if canonical.strip().casefold() == label_key:
+            return canonical
+    return None
+
+
+def _dedupe_participants(participants: list[Participant]) -> list[Participant]:
+    seen: dict[str, int] = {}
+    result: list[Participant] = []
+    for participant in participants:
+        key = participant.person.label.lower()
+        if key in seen:
+            index = seen[key]
+            existing = result[index]
+            aliases = _unique_labels([*existing.person.aliases, *participant.person.aliases])
+            result[index] = existing.model_copy(
+                update={"person": existing.person.model_copy(update={"aliases": aliases})}
+            )
+            continue
+        seen[key] = len(result)
+        result.append(participant)
+    return result
+
+
+def _person_label_referenced_in_text(label: str, text: str) -> bool:
+    if label in text:
+        return True
+    if _is_full_latin_name(label):
+        first = label.split()[0]
+        return bool(re.search(rf"\b{re.escape(first)}\b", text))
+    return False
+
+
+def _same_person_label(existing: str, candidate: str) -> bool:
+    if existing.lower() == candidate.lower():
+        return True
+    existing_key = existing.strip().lower()
+    candidate_key = candidate.strip().lower()
+    if candidate_key in _latin_name_aliases(existing):
+        return True
+    if existing_key in _latin_name_aliases(candidate):
+        return True
+    return False
+
+
+def _is_full_latin_name(label: str) -> bool:
+    return bool(re.fullmatch(r"[A-Z][A-Za-z'-]+(?:\s+[A-Z][A-Za-z'-]+)+", label.strip()))
+
+
+def _latin_name_aliases(label: str) -> set[str]:
+    if not _is_full_latin_name(label):
+        return set()
+    tokens = label.strip().split()
+    aliases = {tokens[0].lower()}
+    aliases.update(" ".join(tokens[:index]).lower() for index in range(2, len(tokens)))
+    if tokens[0].casefold() == "test" and len(tokens) >= 3:
+        aliases.add(tokens[1].lower())
+        aliases.update(" ".join(tokens[1:index]).lower() for index in range(3, len(tokens)))
+    return aliases
+
+
+def _default_subject(participants: list[Participant]) -> PersonRef | None:
+    if len(participants) == 1:
+        return participants[0].person
+    return None
+
+
+def _optional_metadata(**values: object) -> dict[str, object]:
+    return {key: value.strip() for key, value in values.items() if isinstance(value, str) and value.strip()}
+
+
+def _unique_labels(labels: Iterable[object]) -> list[str]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for label in labels:
+        normalized = str(label).strip()
+        key = normalized.lower()
+        if normalized and key not in seen:
+            seen.add(key)
+            result.append(normalized)
+    return result
+
+
+def _unique_pairs(pairs: list[tuple[str, str]]) -> list[tuple[str, str]]:
+    seen: set[tuple[str, str]] = set()
+    result: list[tuple[str, str]] = []
+    for source, target in pairs:
+        key = (source.lower(), target.lower())
+        if key not in seen:
+            seen.add(key)
+            result.append((source, target))
+    return result
+
+
+def _unique_triples(triples: list[tuple[str, str, str]]) -> list[tuple[str, str, str]]:
+    seen: set[tuple[str, str, str]] = set()
+    result: list[tuple[str, str, str]] = []
+    for source, target, relationship_type in triples:
+        key = (source.lower(), target.lower(), relationship_type)
+        if key not in seen:
+            seen.add(key)
+            result.append((source, target, relationship_type))
+    return result
+
+
+def _is_probable_person(label: str) -> bool:
+    if _is_bad_person_label(label):
+        return False
+    if re.fullmatch(PLACEHOLDER_NAME, label):
+        return True
+    if re.fullmatch(LATIN_NAME, label):
+        blocked = {"Blue Bottle", "Blue Bottle Coffee", "People Square", "West Lake"}
+        return label not in blocked
+    return bool(re.fullmatch(CJK_NAME, label))