osint-investigation

1"""Shared entity-name normalization helpers (stdlib-only).2 3Used by entity_resolution.py and timing_analysis.py.4"""5from __future__ import annotations6 7import re8 9# Legal suffixes / corporate boilerplate to strip during normalization.10_SUFFIX_TOKENS = {11    "INC", "INCORPORATED", "LLC", "LLP", "LP", "LTD", "LIMITED",12    "CORP", "CORPORATION", "CO", "COMPANY",13    "GROUP", "GRP", "HOLDINGS", "HOLDING",14    "PARTNERS", "ASSOCIATES",15    "INTERNATIONAL", "INTL",16    "ENTERPRISES", "ENTERPRISE",17    "SERVICES", "SERVICE", "SVCS",18    "SOLUTIONS", "MANAGEMENT", "MGMT", "CONSULTING",19    "TECHNOLOGY", "TECHNOLOGIES", "TECH",20    "INDUSTRIES", "INDUSTRY",21    "AMERICA", "AMERICAN",22    "USA", "US",23    "PLLC", "PC",24    "TRUST", "FOUNDATION",25}26 27_PUNCT_RE = re.compile(r"[^\w\s]")28_WS_RE = re.compile(r"\s+")29 30 31def normalize_name(name: str | None) -> str:32    """Standard normalization: uppercase, strip suffixes, drop punctuation."""33    if not name:34        return ""35    s = _PUNCT_RE.sub(" ", name.upper())36    s = _WS_RE.sub(" ", s).strip()37    tokens = [t for t in s.split() if t and t not in _SUFFIX_TOKENS]38    return " ".join(tokens)39 40 41def normalize_aggressive(name: str | None) -> str:42    """Aggressive normalization: sorted unique tokens (word-bag)."""43    base = normalize_name(name)44    if not base:45        return ""46    return " ".join(sorted(set(base.split())))47 48 49def name_tokens(name: str | None, min_len: int = 4) -> set[str]:50    """Token set used for overlap matching."""51    base = normalize_name(name)52    if not base:53        return set()54    return {t for t in base.split() if len(t) >= min_len}55 56 57def token_overlap_ratio(left: str | None, right: str | None) -> tuple[float, int]:58    """Return (jaccard-like ratio, shared token count) over min-len tokens."""59    a = name_tokens(left)60    b = name_tokens(right)61    if not a or not b:62        return 0.0, 063    shared = a & b64    if not shared:65        return 0.0, 066    union = a | b67    return len(shared) / len(union), len(shared)68