imhcode 1.0.0

package/skills/graphify/cluster.py

@@ -0,0 +1,267 @@
+"""Community detection on NetworkX graphs. Uses Leiden (graspologic) if available, falls back to Louvain (networkx). Splits oversized communities. Returns cohesion scores."""
+from __future__ import annotations
+import contextlib
+import inspect
+import io
+import json
+import sys
+import networkx as nx
+
+
+def _suppress_output():
+    """Context manager to suppress stdout/stderr during library calls.
+
+    graspologic's leiden() emits ANSI escape sequences (progress bars,
+    colored warnings) that corrupt PowerShell 5.1's scroll buffer on
+    Windows (see issue #19). Redirecting stdout/stderr to devnull during
+    the call prevents this without losing any graphify output.
+    """
+    return contextlib.redirect_stdout(io.StringIO())
+
+
+def _partition(G: nx.Graph, resolution: float = 1.0) -> dict[str, int]:
+    """Run community detection. Returns {node_id: community_id}.
+
+    Tries Leiden (graspologic) first — best quality.
+    Falls back to Louvain (built into networkx) if graspologic is not installed.
+
+    resolution > 1.0 → more, smaller communities.
+    resolution < 1.0 → fewer, larger communities.
+
+    Output from graspologic is suppressed to prevent ANSI escape codes
+    from corrupting terminal scroll buffers on Windows PowerShell 5.1.
+    """
+    stable = nx.Graph()
+    stable.add_nodes_from(sorted(G.nodes(), key=str))
+    edge_rows = sorted(
+        G.edges(data=True),
+        key=lambda row: (
+            str(row[0]),
+            str(row[1]),
+            json.dumps(row[2], sort_keys=True, ensure_ascii=False, default=str),
+        ),
+    )
+    for src, tgt, attrs in edge_rows:
+        stable.add_edge(src, tgt, **attrs)
+
+    try:
+        from graspologic.partition import leiden
+        lsig = inspect.signature(leiden).parameters
+        kwargs: dict = {}
+        if "random_seed" in lsig:
+            kwargs["random_seed"] = 42
+        if "trials" in lsig:
+            kwargs["trials"] = 1
+        if "resolution" in lsig:
+            kwargs["resolution"] = resolution
+        # Suppress graspologic output to prevent ANSI escape codes from
+        # corrupting PowerShell 5.1 scroll buffer (issue #19)
+        old_stderr = sys.stderr
+        try:
+            sys.stderr = io.StringIO()
+            with _suppress_output():
+                result = leiden(stable, **kwargs)
+        finally:
+            sys.stderr = old_stderr
+        return result
+    except ImportError:
+        pass
+
+    # Fallback: networkx louvain (available since networkx 2.7).
+    # Inspect kwargs to stay compatible across NetworkX versions — max_level
+    # was added in a later release and prevents hangs on large sparse graphs.
+    kwargs: dict = {"seed": 42, "threshold": 1e-4, "resolution": resolution}
+    if "max_level" in inspect.signature(nx.community.louvain_communities).parameters:
+        kwargs["max_level"] = 10
+    communities = nx.community.louvain_communities(stable, **kwargs)
+    return {node: cid for cid, nodes in enumerate(communities) for node in nodes}
+
+
+_MAX_COMMUNITY_FRACTION = 0.25   # communities larger than 25% of graph get split
+_MIN_SPLIT_SIZE = 10             # only split if community has at least this many nodes
+_COHESION_SPLIT_THRESHOLD = 0.05 # re-split communities with cohesion below this
+_COHESION_SPLIT_MIN_SIZE = 50    # only cohesion-split if community has at least this many nodes
+
+
+def cluster(
+    G: nx.Graph,
+    resolution: float = 1.0,
+    exclude_hubs_percentile: float | None = None,
+) -> dict[int, list[str]]:
+    """Run Leiden community detection. Returns {community_id: [node_ids]}.
+
+    Community IDs are stable across runs: 0 = largest community after splitting.
+    Oversized communities (> 25% of graph nodes, min 10) are split by running
+    a second Leiden pass on the subgraph.
+
+    Accepts directed or undirected graphs. DiGraphs are converted to undirected
+    internally since Louvain/Leiden require undirected input.
+
+    resolution: passed to Leiden/Louvain. >1.0 = more smaller communities,
+        <1.0 = fewer larger communities. Default 1.0.
+    exclude_hubs_percentile: if set (0-100), nodes whose degree exceeds this
+        percentile are excluded from partitioning and reattached to their
+        majority-vote neighbour community afterwards. Useful for staging/utility
+        super-hubs that inflate god-node rankings (#919).
+    """
+    if G.number_of_nodes() == 0:
+        return {}
+    if G.is_directed():
+        G = G.to_undirected()
+    if G.number_of_edges() == 0:
+        return {i: [n] for i, n in enumerate(sorted(G.nodes))}
+
+    # Compute hub exclusion set before removing anything so degree is based on full graph
+    hub_nodes: set[str] = set()
+    if exclude_hubs_percentile is not None:
+        degrees = sorted(d for _, d in G.degree())
+        if degrees:
+            idx = max(0, int(len(degrees) * exclude_hubs_percentile / 100) - 1)
+            threshold = degrees[idx]
+            hub_nodes = {n for n, d in G.degree() if d > threshold}
+
+    # Leiden warns and drops isolates - handle them separately
+    # Also exclude hub nodes from partitioning so they don't pull unrelated
+    # subsystems into the same community
+    excluded = hub_nodes
+    isolates = [n for n in G.nodes() if G.degree(n) == 0 and n not in excluded]
+    connected_nodes = [n for n in G.nodes() if G.degree(n) > 0 and n not in excluded]
+    connected = G.subgraph(connected_nodes)
+
+    raw: dict[int, list[str]] = {}
+    if connected.number_of_nodes() > 0:
+        partition = _partition(connected, resolution=resolution)
+        for node, cid in partition.items():
+            raw.setdefault(cid, []).append(node)
+
+    # Each isolate becomes its own single-node community
+    next_cid = max(raw.keys(), default=-1) + 1
+    for node in isolates:
+        raw[next_cid] = [node]
+        next_cid += 1
+
+    # Reattach excluded hubs by majority-vote neighbour community
+    if hub_nodes:
+        node_community: dict[str, int] = {n: cid for cid, nodes in raw.items() for n in nodes}
+        for hub in sorted(hub_nodes):
+            votes: dict[int, int] = {}
+            for nb in G.neighbors(hub):
+                cid = node_community.get(nb)
+                if cid is not None:
+                    votes[cid] = votes.get(cid, 0) + 1
+            if votes:
+                best = min(votes, key=lambda c: (-votes[c], c))
+                raw.setdefault(best, []).append(hub)
+                node_community[hub] = best
+            else:
+                raw[next_cid] = [hub]
+                node_community[hub] = next_cid
+                next_cid += 1
+
+    # Split oversized communities
+    max_size = max(_MIN_SPLIT_SIZE, int(G.number_of_nodes() * _MAX_COMMUNITY_FRACTION))
+    final_communities: list[list[str]] = []
+    for nodes in raw.values():
+        if len(nodes) > max_size:
+            final_communities.extend(_split_community(G, nodes))
+        else:
+            final_communities.append(nodes)
+
+    # Second pass: re-split low-cohesion communities caused by doc-hub nodes
+    # that bridge otherwise-unrelated subsystems (e.g. CLAUDE.md connected to everything).
+    second_pass: list[list[str]] = []
+    for nodes in final_communities:
+        if len(nodes) >= _COHESION_SPLIT_MIN_SIZE and cohesion_score(G, nodes) < _COHESION_SPLIT_THRESHOLD:
+            splits = _split_community(G, nodes)
+            second_pass.extend(splits if len(splits) > 1 else [nodes])
+        else:
+            second_pass.append(nodes)
+    final_communities = second_pass
+
+    # Re-index by size descending for deterministic ordering
+    final_communities.sort(key=len, reverse=True)
+    return {i: sorted(nodes) for i, nodes in enumerate(final_communities)}
+
+
+def _split_community(G: nx.Graph, nodes: list[str]) -> list[list[str]]:
+    """Run a second Leiden pass on a community subgraph to split it further."""
+    subgraph = G.subgraph(nodes)
+    if subgraph.number_of_edges() == 0:
+        # No edges - split into individual nodes
+        return [[n] for n in sorted(nodes)]
+    try:
+        sub_partition = _partition(subgraph)
+        sub_communities: dict[int, list[str]] = {}
+        for node, cid in sub_partition.items():
+            sub_communities.setdefault(cid, []).append(node)
+        if len(sub_communities) <= 1:
+            return [sorted(nodes)]
+        return [sorted(v) for v in sub_communities.values()]
+    except Exception:
+        return [sorted(nodes)]
+
+
+def cohesion_score(G: nx.Graph, community_nodes: list[str]) -> float:
+    """Ratio of actual intra-community edges to maximum possible."""
+    n = len(community_nodes)
+    if n <= 1:
+        return 1.0
+    subgraph = G.subgraph(community_nodes)
+    actual = subgraph.number_of_edges()
+    possible = n * (n - 1) / 2
+    return actual / possible if possible > 0 else 0.0
+
+
+def score_all(G: nx.Graph, communities: dict[int, list[str]]) -> dict[int, float]:
+    return {cid: cohesion_score(G, nodes) for cid, nodes in communities.items()}
+
+
+def remap_communities_to_previous(
+    communities: dict[int, list[str]],
+    previous_node_community: dict[str, int],
+) -> dict[int, list[str]]:
+    """Remap community IDs to maximize overlap with a previous assignment.
+
+    Uses greedy one-to-one matching by intersection size, then assigns fresh IDs
+    to unmatched communities in deterministic order (size desc, lexical tie-break).
+    """
+    if not communities:
+        return {}
+
+    new_sets = {cid: set(nodes) for cid, nodes in communities.items()}
+    old_sets: dict[int, set[str]] = {}
+    for node, old_cid in previous_node_community.items():
+        old_sets.setdefault(old_cid, set()).add(node)
+
+    overlaps: list[tuple[int, int, int]] = []
+    for old_cid, old_nodes in old_sets.items():
+        for new_cid, new_nodes in new_sets.items():
+            overlap = len(old_nodes & new_nodes)
+            if overlap > 0:
+                overlaps.append((overlap, old_cid, new_cid))
+    overlaps.sort(key=lambda x: (-x[0], x[1], x[2]))
+
+    new_to_final: dict[int, int] = {}
+    used_old_ids: set[int] = set()
+    matched_new_ids: set[int] = set()
+    for _overlap, old_cid, new_cid in overlaps:
+        if old_cid in used_old_ids or new_cid in matched_new_ids:
+            continue
+        new_to_final[new_cid] = old_cid
+        used_old_ids.add(old_cid)
+        matched_new_ids.add(new_cid)
+
+    unmatched = [cid for cid in communities if cid not in matched_new_ids]
+    unmatched.sort(key=lambda cid: (-len(communities[cid]), tuple(sorted(communities[cid]))))
+    next_id = 0
+    for new_cid in unmatched:
+        while next_id in used_old_ids:
+            next_id += 1
+        new_to_final[new_cid] = next_id
+        used_old_ids.add(next_id)
+        next_id += 1
+
+    remapped: dict[int, list[str]] = {}
+    for new_cid, nodes in communities.items():
+        remapped[new_to_final[new_cid]] = sorted(nodes)
+    return dict(sorted(remapped.items(), key=lambda kv: kv[0]))

package/skills/graphify/dedup.py

@@ -0,0 +1,414 @@
+"""Entity deduplication pipeline for graphify knowledge graphs.
+
+Pipeline: exact normalization → entropy gate → MinHash/LSH blocking →
+Jaro-Winkler verification → same-community boost → union-find merge.
+"""
+from __future__ import annotations
+import math
+import re
+from collections import defaultdict
+
+from datasketch import MinHash, MinHashLSH
+from rapidfuzz.distance import JaroWinkler
+
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+def _norm(label: str) -> str:
+    """Lowercase + collapse non-alphanumeric runs to space."""
+    return re.sub(r"[^a-z0-9]+", " ", label.lower()).strip()
+
+
+def _entropy(label: str) -> float:
+    """Shannon entropy in bits/char of the normalised label."""
+    s = _norm(label)
+    if not s:
+        return 0.0
+    freq: dict[str, int] = defaultdict(int)
+    for ch in s:
+        freq[ch] += 1
+    n = len(s)
+    return -sum((c / n) * math.log2(c / n) for c in freq.values())
+
+
+def _shingles(text: str, k: int = 3) -> set[str]:
+    """Return k-gram character shingles of text."""
+    if len(text) < k:
+        return {text}
+    return {text[i : i + k] for i in range(len(text) - k + 1)}
+
+
+def _make_minhash(text: str, num_perm: int = 128) -> MinHash:
+    # Strip spaces so "graph extractor" and "graphextractor" share shingles
+    m = MinHash(num_perm=num_perm)
+    for shingle in _shingles(text.replace(" ", "")):
+        m.update(shingle.encode("utf-8"))
+    return m
+
+
+# Matches labels whose trailing token is a version/variant suffix:
+# digits optionally followed by letters (chip SKUs: ASR1603, M1, Cortex-A55)
+# or 2+ letters (codename revisions: cranelr vs cranel).
+# Requires the stem to end in a letter so plain words don't accidentally match.
+_VARIANT_SUFFIX = re.compile(r"^(.*[a-z])([0-9]+[a-z]*|[a-z]{2,})$")
+
+
+def _is_variant_pair(a: str, b: str) -> bool:
+    """True if a and b are sibling model/SKU variants (same stem, different suffix).
+
+    Only applied to short labels (< 12 chars); long labels go through JW normally.
+    """
+    if a == b:
+        return False
+    if max(len(a), len(b)) >= 12:
+        return False
+    ma, mb = _VARIANT_SUFFIX.match(a), _VARIANT_SUFFIX.match(b)
+    if not (ma and mb):
+        return False
+    return ma.group(1) == mb.group(1) and ma.group(2) != mb.group(2)
+
+
+def _short_label_blocked(a: str, b: str, jw_score: float) -> bool:
+    """Block fuzzy merge for short labels unless it's a same-length single-char substitution.
+
+    Insertions/deletions on short strings (cranel/cranelr, M1/M1 Pro) produce
+    high Jaro-Winkler scores due to the prefix bonus but are almost never true
+    duplicates — they're abbreviations or variants.
+    """
+    if max(len(a), len(b)) >= 12:
+        return False
+    from rapidfuzz.distance import DamerauLevenshtein
+    # Allow only same-length single-char substitutions (true typos like "Extractor"/"Extractar").
+    # Block length-differing pairs regardless of score.
+    if jw_score >= 97.0 and len(a) == len(b) and DamerauLevenshtein.distance(a, b) <= 1:
+        return False
+    return True
+
+
+# ── union-find ────────────────────────────────────────────────────────────────
+
+class _UF:
+    def __init__(self) -> None:
+        self._parent: dict[str, str] = {}
+
+    def find(self, x: str) -> str:
+        self._parent.setdefault(x, x)
+        while self._parent[x] != x:
+            self._parent[x] = self._parent[self._parent[x]]
+            x = self._parent[x]
+        return x
+
+    def union(self, x: str, y: str) -> None:
+        self._parent.setdefault(x, x)
+        self._parent.setdefault(y, y)
+        rx, ry = self.find(x), self.find(y)
+        if rx != ry:
+            self._parent[ry] = rx
+
+    def components(self) -> dict[str, list[str]]:
+        groups: dict[str, list[str]] = defaultdict(list)
+        for x in self._parent:
+            groups[self.find(x)].append(x)
+        return dict(groups)
+
+
+# ── constants ─────────────────────────────────────────────────────────────────
+
+_ENTROPY_THRESHOLD = 2.5
+_LSH_THRESHOLD = 0.7
+_MERGE_THRESHOLD = 92.0     # rapidfuzz normalized_similarity * 100
+_COMMUNITY_BOOST = 5.0      # score bonus when both nodes share community
+_NUM_PERM = 128
+_CHUNK_SUFFIX = re.compile(r"_c\d+$")
+
+
+# ── main entry point ──────────────────────────────────────────────────────────
+
+def deduplicate_entities(
+    nodes: list[dict],
+    edges: list[dict],
+    *,
+    communities: dict[str, int],
+    dedup_llm_backend: str | None = None,
+) -> tuple[list[dict], list[dict]]:
+    """Deduplicate near-identical entities in a knowledge graph.
+
+    Args:
+        nodes: list of node dicts with at minimum {"id": str, "label": str}
+        edges: list of edge dicts with {"source": str, "target": str, ...}
+        communities: mapping of node_id -> community_id (from cluster())
+        dedup_llm_backend: if set, use LLM to resolve ambiguous pairs
+
+    Returns:
+        (deduped_nodes, deduped_edges) with edges rewired to survivors
+    """
+    # Guard: cross-project dedup is not supported — nodes from different repos
+    # share label names by coincidence and must never be merged by string similarity.
+    # If you need to dedup a global graph, run deduplicate_entities per-repo first.
+    repos_seen = {n.get("repo") for n in nodes if n.get("repo")}
+    if len(repos_seen) > 1:
+        raise ValueError(
+            f"deduplicate_entities: nodes span multiple repos {sorted(repos_seen)!r}. "
+            f"Cross-project dedup is disabled — run dedup per-repo before merging."
+        )
+
+    if len(nodes) <= 1:
+        return nodes, edges
+
+    # Pre-deduplicate: keep first occurrence of each id
+    seen_ids: dict[str, dict] = {}
+    for node in nodes:
+        nid = node.get("id", "")
+        if nid and nid not in seen_ids:
+            seen_ids[nid] = node
+    unique_nodes = list(seen_ids.values())
+
+    if len(unique_nodes) <= 1:
+        return unique_nodes, edges
+
+    # ── pass 1: exact normalization ───────────────────────────────────────────
+    norm_to_nodes: dict[str, list[dict]] = defaultdict(list)
+    for node in unique_nodes:
+        key = _norm(node.get("label", node.get("id", "")))
+        if key:
+            norm_to_nodes[key].append(node)
+
+    uf = _UF()
+    exact_merges = 0
+    for key, group in norm_to_nodes.items():
+        if len(group) <= 1:
+            continue
+        # Partition by source_file — only merge within the same file in Pass 1.
+        # Cross-file matches fall through to Pass 2 fuzzy matching.
+        by_file: dict[str, list[dict]] = defaultdict(list)
+        for node in group:
+            sf = node.get("source_file") or ""
+            by_file[sf].append(node)
+        for file_group in by_file.values():
+            if len(file_group) > 1:
+                winner = _pick_winner(file_group)
+                for node in file_group:
+                    uf.union(winner["id"], node["id"])
+                exact_merges += len(file_group) - 1
+
+    # ── pass 2: MinHash/LSH + Jaro-Winkler (high-entropy nodes only) ─────────
+    candidates: list[dict] = []
+    seen_norms: set[str] = set()
+    for node in unique_nodes:
+        key = _norm(node.get("label", node.get("id", "")))
+        if key and key not in seen_norms:
+            seen_norms.add(key)
+            if _entropy(node.get("label", "")) >= _ENTROPY_THRESHOLD:
+                candidates.append(node)
+
+    fuzzy_merges = 0
+    if len(candidates) >= 2:
+        lsh = MinHashLSH(threshold=_LSH_THRESHOLD, num_perm=_NUM_PERM)
+        minhashes: dict[str, MinHash] = {}
+
+        for node in candidates:
+            norm_label = _norm(node.get("label", node.get("id", "")))
+            m = _make_minhash(norm_label)
+            minhashes[node["id"]] = m
+            try:
+                lsh.insert(node["id"], m)
+            except ValueError:
+                pass  # duplicate key in LSH — already inserted
+
+        for node in candidates:
+            node_id = node["id"]
+            norm_label = _norm(node.get("label", node.get("id", "")))
+            neighbors = lsh.query(minhashes[node_id])
+
+            for neighbor_id in neighbors:
+                if neighbor_id == node_id:
+                    continue
+                if uf.find(node_id) == uf.find(neighbor_id):
+                    continue
+
+                neighbor = next((n for n in candidates if n["id"] == neighbor_id), None)
+                if neighbor is None:
+                    continue
+
+                neighbor_norm = _norm(neighbor.get("label", neighbor.get("id", "")))
+                score = JaroWinkler.normalized_similarity(norm_label, neighbor_norm) * 100
+
+                if _is_variant_pair(norm_label, neighbor_norm):
+                    continue
+                if _short_label_blocked(norm_label, neighbor_norm, score):
+                    continue
+
+                c1 = communities.get(node_id)
+                c2 = communities.get(neighbor_id)
+                if (c1 is not None and c2 is not None and c1 == c2
+                        and min(len(norm_label), len(neighbor_norm)) >= 12):
+                    score += _COMMUNITY_BOOST
+
+                if score >= _MERGE_THRESHOLD:
+                    all_group = norm_to_nodes.get(norm_label, [node]) + \
+                                norm_to_nodes.get(neighbor_norm, [neighbor])
+                    winner = _pick_winner(all_group)
+                    uf.union(winner["id"], node_id)
+                    uf.union(winner["id"], neighbor_id)
+                    fuzzy_merges += 1
+
+    # ── pass 3: LLM tiebreaker for ambiguous pairs (opt-in) ──────────────────
+    if dedup_llm_backend is not None:
+        _llm_tiebreak(candidates, uf, communities, backend=dedup_llm_backend)
+
+    # ── build remap table from union-find components ──────────────────────────
+    components = uf.components()
+    remap: dict[str, str] = {}
+
+    for root, members in components.items():
+        if len(members) == 1:
+            continue
+        group_nodes = [n for n in unique_nodes if n["id"] in members]
+        winner = _pick_winner(group_nodes) if group_nodes else {"id": root}
+        winner_id = winner["id"]
+        for member in members:
+            if member != winner_id:
+                remap[member] = winner_id
+
+    # ── apply remap ───────────────────────────────────────────────────────────
+    if not remap:
+        return unique_nodes, edges
+
+    total = len(remap)
+    msg = f"[graphify] Deduplicated {total} node(s)"
+    if exact_merges:
+        msg += f" ({exact_merges} exact"
+        if fuzzy_merges:
+            msg += f", {fuzzy_merges} fuzzy"
+        msg += ")"
+    print(msg + ".", flush=True)
+
+    deduped_nodes = [n for n in unique_nodes if n["id"] not in remap]
+    deduped_edges = []
+    for edge in edges:
+        e = dict(edge)
+        # Tolerate "from"/"to" keys from LLM backends that don't follow the
+        # schema exactly — build_from_json normalises later but dedup runs
+        # first so bracket access would KeyError here (#803).
+        # Use explicit key presence check (not `or`) so empty-string src/tgt
+        # aren't silently replaced by the fallback key.
+        src = e["source"] if "source" in e else e.get("from")
+        tgt = e["target"] if "target" in e else e.get("to")
+        if src is None or tgt is None:
+            continue
+        e["source"] = remap.get(src, src)
+        e["target"] = remap.get(tgt, tgt)
+        # Remove legacy keys so they don't leak into edge attrs in graph.json.
+        e.pop("from", None)
+        e.pop("to", None)
+        if e["source"] != e["target"]:
+            deduped_edges.append(e)
+
+    return deduped_nodes, deduped_edges
+
+
+def _pick_winner(nodes: list[dict]) -> dict:
+    """Pick the canonical survivor: prefer no chunk suffix, then shorter ID."""
+    if not nodes:
+        raise ValueError("Cannot pick winner from empty list")
+
+    def _score(n: dict) -> tuple[int, int]:
+        has_suffix = bool(_CHUNK_SUFFIX.search(n["id"]))
+        return (1 if has_suffix else 0, len(n["id"]))
+
+    return min(nodes, key=_score)
+
+
+def _llm_tiebreak(
+    candidates: list[dict],
+    uf: _UF,
+    communities: dict[str, int],
+    *,
+    backend: str,
+    batch_size: int = 30,
+    low: float = 75.0,
+    high: float = 92.0,
+) -> None:
+    """Batch-resolve ambiguous pairs (score in [low, high)) via LLM."""
+    try:
+        from graphify.llm import BACKENDS, _format_backend_env_keys, _get_backend_api_key
+        if backend not in BACKENDS:
+            print(f"[graphify] --dedup-llm: unknown backend {backend!r}, skipping LLM tiebreaker.", flush=True)
+            return
+        if not _get_backend_api_key(backend):
+            env_keys = _format_backend_env_keys(backend)
+            print(f"[graphify] --dedup-llm: {env_keys} not set, skipping LLM tiebreaker.", flush=True)
+            return
+    except ImportError:
+        return
+
+    ambiguous: list[tuple[dict, dict, float]] = []
+    for i, node in enumerate(candidates):
+        norm_i = _norm(node.get("label", node.get("id", "")))
+        for j in range(i + 1, len(candidates)):
+            neighbor = candidates[j]
+            if uf.find(node["id"]) == uf.find(neighbor["id"]):
+                continue
+            norm_j = _norm(neighbor.get("label", neighbor.get("id", "")))
+            score = JaroWinkler.normalized_similarity(norm_i, norm_j) * 100
+            if _is_variant_pair(norm_i, norm_j):
+                continue
+            if _short_label_blocked(norm_i, norm_j, score):
+                continue
+            c1 = communities.get(node["id"])
+            c2 = communities.get(neighbor["id"])
+            if (c1 is not None and c2 is not None and c1 == c2
+                    and min(len(norm_i), len(norm_j)) >= 12):
+                score += _COMMUNITY_BOOST
+            if low <= score < high:
+                ambiguous.append((node, neighbor, score))
+
+    if not ambiguous:
+        return
+
+    try:
+        from graphify.llm import _call_llm
+    except ImportError as exc:
+        # F-038: previously this silent fallback hid the fact that `_call_llm`
+        # didn't exist in `graphify.llm` at all, so `--dedup-llm` was a no-op.
+        # Surface the import failure so future regressions are visible.
+        print(
+            f"[graphify] --dedup-llm: cannot import _call_llm ({exc}); skipping LLM tiebreaker.",
+            flush=True,
+        )
+        return
+
+    for batch_start in range(0, len(ambiguous), batch_size):
+        batch = ambiguous[batch_start : batch_start + batch_size]
+        pairs_text = "\n".join(
+            f"{i+1}. \"{a['label']}\" vs \"{b['label']}\""
+            for i, (a, b, _) in enumerate(batch)
+        )
+        prompt = (
+            "For each pair below, answer only 'yes' or 'no': are they the same real-world concept?\n\n"
+            f"{pairs_text}\n\n"
+            "Reply with one line per pair: '1. yes', '2. no', etc."
+        )
+        try:
+            response = _call_llm(prompt, backend=backend, max_tokens=200)
+            lines = response.strip().splitlines()
+            for line in lines:
+                line = line.strip()
+                if not line:
+                    continue
+                parts = line.split(".", 1)
+                if len(parts) != 2:
+                    continue
+                try:
+                    idx = int(parts[0].strip()) - 1
+                except ValueError:
+                    continue
+                if 0 <= idx < len(batch):
+                    answer = parts[1].strip().lower()
+                    if answer.startswith("yes"):
+                        a, b, _ = batch[idx]
+                        winner = _pick_winner([a, b])
+                        uf.union(winner["id"], a["id"])
+                        uf.union(winner["id"], b["id"])
+        except Exception as exc:
+            print(f"[graphify] --dedup-llm batch failed: {exc}", flush=True)