seam-code 0.3.0__py3-none-any.whl

seam/analysis/cluster_naming.py

@@ -0,0 +1,260 @@
+"""Cluster labeling module — deterministic labels with optional LLM naming.
+
+Public API:
+    deterministic_label(members) -> str
+    label_cluster(members, naming_mode, api_key, model) -> tuple[str, str]
+
+Design:
+    - deterministic_label: always available, zero dependencies, no I/O.
+      Derives a label from dominant directory/file prefix + highest-degree symbol.
+      Format: "dir/subdir — symbol_name" (em-dash separator).
+    - label_cluster: dispatches to LLM or deterministic based on naming_mode.
+      LLM path is fully isolated in _call_llm_for_label (stub-able in tests).
+      Any LLM error → silent fallback to deterministic + log warning.
+    - _call_llm_for_label: uses stdlib urllib only. NEVER called by default.
+
+Naming source values:
+    "deterministic" — label from heuristic (always the fallback)
+    "llm"          — label from LLM (only when naming_mode='llm' AND key present)
+
+Import rules:
+    This module imports ONLY stdlib (logging, urllib, json, pathlib, collections).
+    It must NOT import seam.indexer.db, seam.query, seam.server, seam.cli.
+"""
+
+import json
+import logging
+import urllib.error
+import urllib.request
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Timeout for LLM HTTP request (seconds). Fail fast — labeling is best-effort.
+_LLM_TIMEOUT_SECONDS = 10
+
+# Default LLM model when not specified
+_DEFAULT_LLM_MODEL = "gpt-4o-mini"
+
+# Anthropic-compatible API endpoint default (can be overridden in tests)
+_DEFAULT_LLM_ENDPOINT = "https://api.openai.com/v1/chat/completions"
+
+# Generic / non-module directory names. These read as packaging scaffolding,
+# NOT functional areas — labeling a cluster 'src' or 'lib' tells an agent nothing.
+# When the immediate parent dir is one of these, _dominant_dir walks UP the path
+# tree to the first non-generic ancestor (e.g. 'render/src/x.py' → 'render').
+GENERIC_DIRS: frozenset[str] = frozenset({"src", "lib", "app", "pkg", "main", "core", "base"})
+
+
+# ── Public types ──────────────────────────────────────────────────────────────
+
+# Member dict shape (consumed by label functions):
+# {"name": str, "file": str, "degree": int}
+# "degree" = number of edges this symbol has (used to find the "most connected")
+MemberInfo = dict[str, Any]
+
+
+# ── deterministic_label ───────────────────────────────────────────────────────
+
+
+def _module_dir_for_path(file_path: str) -> str | None:
+    """Highest NON-GENERIC module directory on a file's path (P2 two-level labels).
+
+    WHY two-level (vs. the old immediate-parent-only rule): a file like
+    'render/src/widget.py' used to label as 'src' — a packaging dir that names no
+    functional area. We instead walk the directory parts from the LEAF upward and
+    return the FIRST non-generic dir (the immediate parent if it isn't generic,
+    otherwise its first non-generic ancestor). This yields module-level labels
+    ('query', 'analysis', 'render') instead of leaf/scaffolding noise.
+
+    Returns None when the file has no parent dir, or when every directory on the
+    path is generic (e.g. 'src/lib/x.py').
+    """
+    parts = Path(file_path).parts
+    # Drop the filename (last part); only directory components are candidates.
+    dir_parts = parts[:-1]
+    # Walk from the immediate parent (closest to the file) upward toward the root,
+    # returning the first directory name that is NOT a generic scaffolding dir.
+    for name in reversed(dir_parts):
+        if name not in GENERIC_DIRS:
+            return name
+    return None
+
+
+def _dominant_dir(members: list[MemberInfo]) -> str | None:
+    """Most common module DIRECTORY NAME among member files (P2 two-level).
+
+    WHY the dir name, not 'dir/filename': the filename is the noisy part — it
+    produces labels like 'unit/test_query_engine' or 'assets/index-Bb07j4Ym'
+    (a build bundle). The directory alone ('query', 'indexer', 'cli', 'analysis')
+    reads as a functional area. Ties broken alphabetically. None when no member
+    has a non-generic module directory (e.g. a repo-root file or an all-generic path).
+
+    P2 change: uses _module_dir_for_path so generic scaffolding dirs (src/lib/app/…)
+    are skipped in favour of the enclosing module dir.
+    """
+    dirs: list[str] = []
+    for m in members:
+        file_path = m.get("file", "")
+        if file_path:
+            module_dir = _module_dir_for_path(file_path)
+            if module_dir is not None:
+                dirs.append(module_dir)
+    if not dirs:
+        return None
+    counts = Counter(dirs)
+    return min(counts.keys(), key=lambda k: (-counts[k], k))
+
+
+def deterministic_label(members: list[MemberInfo]) -> str:
+    """Derive a human-readable cluster label from its members.
+
+    Label format: "<dominant_dir> — <highest_degree_symbol>"
+    Example: "analysis — resolve_edge"  (NOT "analysis/confidence — resolve_edge")
+
+    The anchor is the highest-degree symbol — the hub that best "names" the
+    community. The directory adds locality WITHOUT the filename noise that made
+    old labels look like file paths (the user-reported confusion). When a file
+    has no parent dir, the label is just the anchor symbol.
+
+    Algorithm:
+        1. Anchor = highest-degree symbol (ties broken by name alphabetically).
+        2. Dir = most common immediate-parent directory name (ties alphabetical).
+        3. Combine as "dir — anchor" (or just "anchor" when no dir is available).
+
+    Args:
+        members: List of MemberInfo dicts with 'name', 'file', 'degree' keys.
+
+    Returns:
+        Non-empty label string. Returns "<unnamed>" on empty input (never raises).
+    """
+    if not members:
+        return "<unnamed>"
+
+    # Anchor: highest-degree symbol (ties broken by name) — the community's hub.
+    anchor = min(
+        members,
+        key=lambda m: (-m.get("degree", 0), m.get("name", "")),
+    ).get("name", "<unknown>")
+
+    dir_name = _dominant_dir(members)
+    if dir_name and dir_name != anchor:
+        return f"{dir_name} — {anchor}"
+    return anchor
+
+
+# ── label_cluster ─────────────────────────────────────────────────────────────
+
+
+def label_cluster(
+    members: list[MemberInfo],
+    naming_mode: str = "deterministic",
+    api_key: str | None = None,
+    model: str | None = None,
+    endpoint: str | None = None,
+) -> tuple[str, str]:
+    """Produce a label for a cluster, returning (label, naming_source).
+
+    Args:
+        members:      List of MemberInfo dicts (name, file, degree).
+        naming_mode:  "deterministic" (default) or "llm".
+        api_key:      API key for LLM; required when naming_mode="llm".
+        model:        LLM model name; uses _DEFAULT_LLM_MODEL when not set.
+        endpoint:     LLM API endpoint; uses _DEFAULT_LLM_ENDPOINT when not set.
+
+    Returns:
+        (label, naming_source) where naming_source ∈ {"deterministic", "llm"}.
+        The LLM path is only tried when naming_mode="llm" AND api_key is present.
+        Any LLM error falls back to deterministic silently.
+
+    WHY: The naming_source is stored in the clusters table so operators can see
+    which names were AI-generated vs. heuristic-derived.
+    """
+    if naming_mode != "llm" or not api_key:
+        # Deterministic mode or no key provided — never touch network code
+        return deterministic_label(members), "deterministic"
+
+    # LLM path: try to call, fall back on ANY error
+    try:
+        llm_label = _call_llm_for_label(
+            members,
+            api_key=api_key,
+            model=model or _DEFAULT_LLM_MODEL,
+            endpoint=endpoint or _DEFAULT_LLM_ENDPOINT,
+        )
+        if llm_label and llm_label.strip():
+            return llm_label.strip(), "llm"
+        # Empty/blank response → fall through to deterministic
+        logger.warning("cluster_naming: LLM returned empty label, using deterministic fallback")
+        return deterministic_label(members), "deterministic"
+
+    except Exception as exc:
+        # Any error (network, timeout, bad JSON, missing key) is fail-safe
+        logger.warning(
+            "cluster_naming: LLM naming failed (%s: %s) — using deterministic fallback",
+            type(exc).__name__,
+            exc,
+        )
+        return deterministic_label(members), "deterministic"
+
+
+# ── _call_llm_for_label ────────────────────────────────────────────────────────
+
+
+def _call_llm_for_label(
+    members: list[MemberInfo],
+    api_key: str,
+    model: str = _DEFAULT_LLM_MODEL,
+    endpoint: str = _DEFAULT_LLM_ENDPOINT,
+) -> str:
+    """Call an OpenAI-compatible LLM API to generate a cluster label.
+
+    Uses stdlib urllib only — no external SDK. This is intentionally isolated
+    so tests can monkeypatch this function without touching urllib.
+
+    WHY: Isolated here (not inlined in label_cluster) so tests can stub it
+    via `patch('seam.analysis.cluster_naming._call_llm_for_label')`.
+
+    Args:
+        members:  List of MemberInfo dicts.
+        api_key:  Bearer token for the API.
+        model:    Model name string.
+        endpoint: Full URL to the chat completions endpoint.
+
+    Returns:
+        The label string from the LLM response (may be empty).
+
+    Raises:
+        Any exception from urllib or JSON parsing — caller handles these.
+    """
+    # Build a concise prompt from member names and files
+    symbol_list = ", ".join(m.get("name", "") for m in members[:20])  # cap at 20
+    prompt = (
+        f"Name this code cluster in 3-5 words. Members: {symbol_list}. "
+        "Respond with ONLY the cluster name, no explanation."
+    )
+
+    payload = json.dumps({
+        "model": model,
+        "messages": [{"role": "user", "content": prompt}],
+        "max_tokens": 20,
+        "temperature": 0,  # deterministic response
+    }).encode("utf-8")
+
+    req = urllib.request.Request(
+        endpoint,
+        data=payload,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+
+    with urllib.request.urlopen(req, timeout=_LLM_TIMEOUT_SECONDS) as response:
+        body = json.loads(response.read().decode("utf-8"))
+
+    # Extract content from OpenAI-compatible response shape
+    return body["choices"][0]["message"]["content"]

seam/analysis/clustering.py

@@ -0,0 +1,216 @@
+"""Pure community detection module — Louvain greedy modularity maximization.
+
+Public API:
+    detect_communities(nodes, edges) -> dict[str, int]
+
+This is a DEEP PURE module: graph in → cluster map out.
+No SQLite, no file I/O, no config, no side effects.
+
+Design decisions:
+    - Pure-Python Louvain (greedy modularity). No external deps.
+    - Determinism is load-bearing: nodes are sorted before processing,
+      and tie-breaking is always deterministic (sort by community label).
+    - Singleton/disconnected nodes each get their own cluster ID.
+    - Self-loops are ignored (they don't affect modularity).
+    - Edges referencing unknown nodes are safely ignored.
+    - Empty graph → {}.
+    - Never raises on any input — returns sensible degraded output.
+
+Algorithm (standard Louvain phase 1 — modularity maximization):
+    1. Assign each node to its own singleton community.
+    2. For each node (in sorted order), try moving it to each neighbor's
+       community. Accept the move with the highest positive modularity gain.
+    3. Repeat until no node moves in a full pass (convergence) or
+       _MAX_ITERATIONS is reached.
+    4. Renumber community IDs as stable integers (sorted by min member name).
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Maximum passes over all nodes. Prevents infinite loops on pathological graphs.
+_MAX_ITERATIONS = 100
+
+
+def detect_communities(
+    nodes: list[str],
+    edges: list[tuple[str, str]],
+) -> dict[str, int]:
+    """Detect communities in an undirected graph using Louvain modularity optimization.
+
+    Args:
+        nodes: List of node names (symbol names). Duplicates are deduplicated.
+        edges: List of (source, target) pairs. Directed edges are treated as
+               undirected (both directions considered). Edges to unknown nodes
+               are silently ignored.
+
+    Returns:
+        Dict mapping each node name to an integer cluster ID.
+        Empty dict when nodes is empty.
+        Cluster IDs are stable integers starting at 0, ordered by the
+        lexicographically smallest member of each community (deterministic).
+
+    Never raises. On any internal error, logs a warning and returns
+    each node in its own singleton cluster.
+    """
+    if not nodes:
+        return {}
+
+    try:
+        return _detect_communities_impl(nodes, edges)
+    except Exception as exc:
+        logger.warning(
+            "clustering: detect_communities failed with %s — falling back to singletons",
+            exc,
+        )
+        # Deterministic fallback: each node its own cluster (sorted for stability)
+        sorted_unique = sorted(set(nodes))
+        return {n: i for i, n in enumerate(sorted_unique)}
+
+
+def _detect_communities_impl(
+    nodes: list[str],
+    edges: list[tuple[str, str]],
+) -> dict[str, int]:
+    """Inner implementation — may raise; outer function catches and degrades."""
+    # Deduplicate and sort nodes for deterministic processing order
+    unique_nodes = sorted(set(nodes))
+
+    if not unique_nodes:
+        return {}
+
+    # Build undirected adjacency sets — only between known nodes
+    node_set = set(unique_nodes)
+    adj: dict[str, set[str]] = {n: set() for n in unique_nodes}
+
+    for src, tgt in edges:
+        if src == tgt:
+            # Self-loops don't affect modularity — skip
+            continue
+        if src in node_set and tgt in node_set:
+            adj[src].add(tgt)
+            adj[tgt].add(src)
+
+    # m = total number of undirected edges (used in modularity formula)
+    # Count half-sum of all degrees (each undirected edge appears twice in degree sum)
+    degree: dict[str, int] = {n: len(adj[n]) for n in unique_nodes}
+    m = sum(degree.values()) // 2  # undirected edge count
+
+    # Each node starts in its own singleton community (labeled by the node name)
+    # Using node names as community labels ensures determinism: no integer IDs
+    # that depend on insertion order.
+    community: dict[str, str] = {n: n for n in unique_nodes}
+
+    # community_degree[comm]: sum of degrees of all nodes in community comm
+    community_degree: dict[str, int] = {n: degree[n] for n in unique_nodes}
+
+    if m == 0:
+        # No edges → every node is its own singleton; assign stable int IDs
+        return _assign_stable_ids(community, unique_nodes)
+
+    # Louvain phase 1: iterate until no node moves
+    for _iteration in range(_MAX_ITERATIONS):
+        improved = False
+
+        # Process nodes in deterministic sorted order
+        for node in unique_nodes:
+            current_comm = community[node]
+            node_deg = degree[node]
+
+            # Count edges from this node into each neighboring community
+            # k_in[comm] = number of edges from node to members of comm
+            k_in: dict[str, int] = {}
+            for neighbor in adj[node]:
+                nc = community[neighbor]
+                k_in[nc] = k_in.get(nc, 0) + 1
+
+            # Remove node from current community (to evaluate re-insertion)
+            community_degree[current_comm] -= node_deg
+            k_in_current = k_in.get(current_comm, 0)
+
+            # Find best community using Louvain modularity gain formula:
+            #   ΔQ ∝ k_in_C - (Σ_tot * k_i) / (2m)
+            # We compare against the "remove" baseline (k_in=0, sigma_tot=0),
+            # so the "stay" option is evaluated fairly.
+            # WHY: Using 2*m as denominator normalization for the degree term.
+            best_comm = current_comm
+            # Gain of reinserting into the current community after removal
+            best_gain = _modularity_gain(k_in_current, community_degree[current_comm], node_deg, m)
+
+            # Evaluate all neighbor communities (sorted for deterministic tie-breaking)
+            for cand_comm in sorted(k_in.keys()):
+                if cand_comm == current_comm:
+                    continue
+                gain = _modularity_gain(k_in[cand_comm], community_degree[cand_comm], node_deg, m)
+                # Accept strictly better gain; on equal gain, prefer smaller community label
+                # (lexicographic tie-break ensures determinism)
+                if gain > best_gain or (gain == best_gain and cand_comm < best_comm):
+                    best_gain = gain
+                    best_comm = cand_comm
+
+            # Reinsert node into best community (may be the same as current)
+            community[node] = best_comm
+            community_degree[best_comm] += node_deg
+
+            if best_comm != current_comm:
+                improved = True
+
+        if not improved:
+            break
+
+    return _assign_stable_ids(community, unique_nodes)
+
+
+def _modularity_gain(k_in: int, sigma_tot: int, k_i: int, m: int) -> float:
+    """Compute the modularity gain of inserting a node into a community.
+
+    Formula: ΔQ = k_in/m - (sigma_tot * k_i) / (2 * m^2)
+
+    Args:
+        k_in: Number of edges from the node to existing community members.
+        sigma_tot: Total degree of the community (after removing the node).
+        k_i: Degree of the node being placed.
+        m: Total number of undirected edges in the graph.
+
+    WHY: This is the standard Louvain gain formula from Blondel et al. (2008).
+    We use floating point division to handle fractional gains correctly.
+    """
+    if m == 0:
+        return 0.0
+    return float(k_in) / m - (sigma_tot * k_i) / (2.0 * m * m)
+
+
+def _assign_stable_ids(
+    community: dict[str, str],
+    sorted_nodes: list[str],
+) -> dict[str, int]:
+    """Assign stable integer IDs to communities.
+
+    WHY: Internal community labels (node name strings) are arbitrary identifiers
+    used during the algorithm. We convert them to stable integers by sorting
+    communities by their lexicographically smallest member — so the same logical
+    partition always gets the same integer IDs.
+
+    Args:
+        community: Mapping of node -> community label (internal string).
+        sorted_nodes: All nodes in sorted order.
+
+    Returns:
+        Dict of node -> integer cluster ID starting at 0.
+    """
+    # Collect the minimum member name per community (for sorting)
+    comm_min_member: dict[str, str] = {}
+    for node in sorted_nodes:
+        comm_label = community[node]
+        if comm_label not in comm_min_member:
+            comm_min_member[comm_label] = node
+        else:
+            if node < comm_min_member[comm_label]:
+                comm_min_member[comm_label] = node
+
+    # Sort community labels by their minimum member → deterministic integer IDs
+    sorted_comm_labels = sorted(comm_min_member.keys(), key=lambda c: comm_min_member[c])
+    comm_to_int: dict[str, int] = {label: i for i, label in enumerate(sorted_comm_labels)}
+
+    return {node: comm_to_int[community[node]] for node in sorted_nodes}