graphify-vault 0.3.2__tar.gz → 0.3.4__tar.gz

{graphify_vault-0.3.2/graphify_vault.egg-info → graphify_vault-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphify_vault
-Version: 0.3.2
+Version: 0.3.4
 Summary: Fork of github.com/safishamsi/graphify with GRAPHIFY_WORKSPACE path resolution for distributed graph artifacts, same-label node merging, incremental build fixes, and local knowledge vault capabilities
 License: MIT License
         
@@ -56,6 +56,9 @@ Requires-Dist: tree-sitter-julia
 Requires-Dist: tree-sitter-verilog
 Provides-Extra: mcp
 Requires-Dist: mcp; extra == "mcp"
+Requires-Dist: deep-translator; extra == "mcp"
+Requires-Dist: pypdf; extra == "mcp"
+Requires-Dist: html2text; extra == "mcp"
 Provides-Extra: neo4j
 Requires-Dist: neo4j; extra == "neo4j"
 Provides-Extra: pdf
@@ -75,6 +78,7 @@ Requires-Dist: faster-whisper; extra == "video"
 Requires-Dist: yt-dlp; extra == "video"
 Provides-Extra: all
 Requires-Dist: mcp; extra == "all"
+Requires-Dist: deep-translator; extra == "all"
 Requires-Dist: neo4j; extra == "all"
 Requires-Dist: pypdf; extra == "all"
 Requires-Dist: html2text; extra == "all"

{graphify_vault-0.3.2 → graphify_vault-0.3.4}/graphify/__main__.py

@@ -1422,7 +1422,7 @@ def main() -> None:
             sys.exit(1)
         from networkx.readwrite import json_graph as _jg
         from graphify.build import build_from_json
-        from graphify.cluster import cluster, score_all
+        from graphify.cluster import cluster, score_all, label_communities
         from graphify.analyze import god_nodes, surprising_connections, suggest_questions
         from graphify.report import generate
         from graphify.export import to_json, to_html
@@ -1435,7 +1435,7 @@ def main() -> None:
         cohesion = score_all(G, communities)
         gods = god_nodes(G)
         surprises = surprising_connections(G, communities)
-        labels = {cid: f"Community {cid}" for cid in communities}
+        labels = label_communities(G, communities)
         questions = suggest_questions(G, communities, labels)
         tokens = {"input": 0, "output": 0}
         report = generate(G, communities, cohesion, labels, gods, surprises,

{graphify_vault-0.3.2 → graphify_vault-0.3.4}/graphify/cluster.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import contextlib
 import inspect
 import io
+import re
 import sys
 import networkx as nx
 
@@ -18,6 +19,87 @@ def _suppress_output():
     return contextlib.redirect_stdout(io.StringIO())
 
 
+def _label_token_overlap(label_a: str, label_b: str) -> float:
+    """Compute token overlap ratio between two labels.
+
+    Splits labels into lowercase tokens using both non-alphanumeric
+    boundaries AND camelCase/PascalCase boundaries. Returns the
+    Jaccard similarity of the token sets. This provides a lightweight
+    semantic similarity signal without requiring any external NLP models.
+    """
+    def _tokens(text: str) -> set[str]:
+        # Split on non-alphanumeric boundaries
+        parts = re.split(r'[^a-zA-Z0-9]+', text)
+        # Also split camelCase/PascalCase: "VideoComponent" -> "Video", "Component"
+        expanded = []
+        for part in parts:
+            # Split on camelCase boundaries: lowercase followed by uppercase
+            sub_parts = re.sub(r'([a-z])([A-Z])', r'\1 \2', part).split()
+            # Split on acronyms: uppercase followed by uppercase+lowercase (e.g., "XMLParser" -> "XML", "Parser")
+            sub_parts = [re.sub(r'([A-Z]+)([A-Z][a-z])', r'\1 \2', s).split() for s in sub_parts]
+            expanded.extend([t for group in sub_parts for t in group])
+        return {t.lower() for t in expanded if len(t) > 2}
+    ta = _tokens(label_a)
+    tb = _tokens(label_b)
+    if not ta or not tb:
+        return 0.0
+    intersection = ta & tb
+    union = ta | tb
+    return len(intersection) / len(union) if union else 0.0
+
+
+def _add_semantic_edges(G: nx.Graph, weight: float = 0.3) -> nx.Graph:
+    """Add weak semantic edges between nodes with overlapping labels.
+
+    For each pair of nodes in the same connected component that share
+    label tokens (Jaccard > 0.3), adds a 'semantically_similar_to' edge
+    with the given weight. These edges guide Leiden/Louvain to group
+    semantically related nodes together even without structural edges.
+
+    This is a non-destructive overlay: the original graph is copied and
+    only new edges are added (no existing edges are modified).
+    """
+    if G.number_of_nodes() < 2:
+        return G.copy()
+
+    # Only consider nodes with meaningful labels
+    candidates = []
+    for nid in G.nodes:
+        label = str(G.nodes[nid].get("label", ""))
+        if label and len(label) > 2:
+            candidates.append((nid, label))
+
+    if len(candidates) < 2:
+        return G.copy()
+
+    G_augmented = G.copy()
+    added = 0
+
+    # For efficiency, only check pairs within the same connected component
+    # and limit to reasonable graph sizes
+    if len(candidates) > 5000:
+        # For very large graphs, sample pairs from same-neighborhood
+        return G_augmented
+
+    for i in range(len(candidates)):
+        nid_a, label_a = candidates[i]
+        for j in range(i + 1, len(candidates)):
+            nid_b, label_b = candidates[j]
+            # Skip if already connected by an edge
+            if G_augmented.has_edge(nid_a, nid_b):
+                continue
+            similarity = _label_token_overlap(label_a, label_b)
+            if similarity > 0.3:
+                G_augmented.add_edge(nid_a, nid_b,
+                                     relation="semantically_similar_to",
+                                     confidence="INFERRED",
+                                     confidence_score=round(similarity, 2),
+                                     weight=weight * similarity)
+                added += 1
+
+    return G_augmented
+
+
 def _partition(G: nx.Graph) -> dict[str, int]:
     """Run community detection. Returns {node_id: community_id}.
 
@@ -56,7 +138,7 @@ _MAX_COMMUNITY_FRACTION = 0.25   # communities larger than 25% of graph get spli
 _MIN_SPLIT_SIZE = 10             # only split if community has at least this many nodes
 
 
-def cluster(G: nx.Graph) -> dict[int, list[str]]:
+def cluster(G: nx.Graph, *, semantic: bool = True) -> dict[int, list[str]]:
     """Run Leiden community detection. Returns {community_id: [node_ids]}.
 
     Community IDs are stable across runs: 0 = largest community after splitting.
@@ -65,6 +147,10 @@ def cluster(G: nx.Graph) -> dict[int, list[str]]:
 
     Accepts directed or undirected graphs. DiGraphs are converted to undirected
     internally since Louvain/Leiden require undirected input.
+
+    If semantic=True (default), weak semantic edges are added between nodes
+    with overlapping labels before clustering, helping semantically related
+    nodes group together even without structural edges.
     """
     if G.number_of_nodes() == 0:
         return {}
@@ -73,6 +159,10 @@ def cluster(G: nx.Graph) -> dict[int, list[str]]:
     if G.number_of_edges() == 0:
         return {i: [n] for i, n in enumerate(sorted(G.nodes))}
 
+    # Optionally augment graph with semantic edges for better community detection
+    if semantic:
+        G = _add_semantic_edges(G)
+
     # Leiden warns and drops isolates - handle them separately
     isolates = [n for n in G.nodes() if G.degree(n) == 0]
     connected_nodes = [n for n in G.nodes() if G.degree(n) > 0]
@@ -133,5 +223,24 @@ def cohesion_score(G: nx.Graph, community_nodes: list[str]) -> float:
     return round(actual / possible, 2) if possible > 0 else 0.0
 
 
+def label_communities(G: nx.Graph, communities: dict[int, list[str]]) -> dict[int, str]:
+    """Generate semantic labels for communities based on highest-degree node.
+
+    For each community, the node with the highest degree (most connections)
+    is chosen as the representative label. This is a simple, universal heuristic
+    that works for any graph without domain-specific knowledge.
+    """
+    labels: dict[int, str] = {}
+    for cid, node_ids in communities.items():
+        if not node_ids:
+            labels[cid] = f"Community {cid}"
+            continue
+        # Find the node with highest degree in this community
+        best_node = max(node_ids, key=lambda n: G.degree(n) if n in G else 0)
+        label = G.nodes[best_node].get("label", best_node) if best_node in G else best_node
+        labels[cid] = label
+    return labels
+
+
 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()}

{graphify_vault-0.3.2 → graphify_vault-0.3.4}/graphify/doctor.py

@@ -66,6 +66,13 @@ def _check_graphify_installed() -> bool:
         )
         if result.returncode == 0:
             _ok(f"graphify {__version__}")
+            # Check for conflicting graphifyy installation
+            try:
+                from importlib.metadata import version as _v, PackageNotFoundError
+                _v("graphifyy")
+                _warn("Both graphify_vault and graphifyy detected. 'graphify' command may point to graphifyy. Use 'gv' command instead, or uninstall graphifyy.")
+            except PackageNotFoundError:
+                pass
             return True
     except Exception:
         pass

{graphify_vault-0.3.2 → graphify_vault-0.3.4}/graphify/extract.py

@@ -231,7 +231,7 @@ def extract_document(path: Path, root: Path | None = None) -> dict:
         return {"nodes": [], "edges": []}
 
     definitions: list[dict[str, Any]] = []
-    headings: list[tuple[str, int]] = []
+    headings: list[tuple[str, int, int]] = []  # (heading, lineno, level)
     seen_labels: set[str] = set()
 
     # Pre-strip lines that are raw HTML (SVG, embedded widgets, etc.)
@@ -246,8 +246,9 @@ def extract_document(path: Path, root: Path | None = None) -> dict:
         m = re.match(r'^(#{1,6})\s+(.+)', line)
         if m:
             heading = m.group(2).strip()
+            level = len(m.group(1))
             if _looks_like_symbol_heading(heading):
-                headings.append((heading, lineno))
+                headings.append((heading, lineno, level))
 
         match = _DOC_DEF_RE.search(line)
         if not match:
@@ -270,7 +271,7 @@ def extract_document(path: Path, root: Path | None = None) -> dict:
         definitions.append({"label": label, "lineno": lineno, "bases": bases})
         seen_labels.add(label)
 
-    for heading, lineno in headings:
+    for heading, lineno, _level in headings:
         if heading not in seen_labels:
             definitions.append({"label": heading, "lineno": lineno, "bases": []})
             seen_labels.add(heading)
@@ -297,7 +298,7 @@ def extract_document(path: Path, root: Path | None = None) -> dict:
                 seen_labels.add(name)
 
     heading_positions: dict[str, list[int]] = {}
-    for heading, lineno in headings:
+    for heading, lineno, _level in headings:
         heading_positions.setdefault(heading, []).append(lineno)
 
     lines = text.splitlines()
@@ -316,7 +317,7 @@ def extract_document(path: Path, root: Path | None = None) -> dict:
     for idx, item in enumerate(definitions):
         next_heading_lineno = None
         current_lineno = int(item["lineno"])
-        for heading, heading_lineno in headings:
+        for heading, heading_lineno, _level in headings:
             if heading_lineno > current_lineno:
                 next_heading_lineno = heading_lineno
                 break
@@ -468,6 +469,289 @@ def _resolve_document_cross_references(
     return new_edges
 
 
+def _add_heading_structure_edges(
+    doc_results: list[dict], doc_paths: list[Path], root: Path | None = None,
+) -> list[dict]:
+    """Add ``contains`` edges based on heading hierarchy within documents.
+
+    For each document, re-parses headings to build a parent-child tree:
+    an H2 heading "contains" all H3 headings under it until the next H2,
+    and so on.  Also creates ``contains`` edges from heading nodes to
+    concept nodes (definitions) that fall under that heading section.
+    """
+    _HEADING_RE = re.compile(r'^(#{1,6})\s+(.+)', re.MULTILINE)
+
+    new_edges: list[dict] = []
+    seen_pairs: set[tuple[str, str]] = set()
+
+    for result, path in zip(doc_results, doc_paths):
+        relpath = _doc_relpath(path, root)
+        stem = _doc_file_stem(path)
+        nodes = result.get("nodes", [])
+        if not nodes:
+            continue
+
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+
+        # Parse all headings with levels
+        all_headings: list[tuple[str, int, int]] = []  # (heading, lineno, level)
+        for m in _HEADING_RE.finditer(text):
+            heading = m.group(2).strip()
+            level = len(m.group(1))
+            # Calculate line number from match position
+            lineno = text[:m.start()].count("\n") + 1
+            all_headings.append((heading, lineno, level))
+
+        if not all_headings:
+            continue
+
+        # Build heading node ID map: heading label → nid
+        heading_nid_map: dict[str, str] = {}
+        for n in nodes:
+            heading_nid_map[n.get("label", "")] = n.get("id", "")
+
+        # Build parent-child heading relationships using a stack
+        # Stack contains (heading, lineno, level, nid)
+        stack: list[tuple[str, int, int, str]] = []
+        heading_contains: list[tuple[str, str]] = []  # (parent_nid, child_nid)
+
+        for heading, lineno, level in all_headings:
+            nid = heading_nid_map.get(heading, _make_id(stem, heading))
+            # Pop stack until we find a parent (lower level number = higher rank)
+            while stack and stack[-1][2] >= level:
+                stack.pop()
+            if stack:
+                parent_nid = stack[-1][3]
+                heading_contains.append((parent_nid, nid))
+            stack.append((heading, lineno, level, nid))
+
+        # Create contains edges for heading hierarchy
+        for parent_nid, child_nid in heading_contains:
+            if parent_nid == child_nid:
+                continue
+            pair = (parent_nid, child_nid)
+            if pair in seen_pairs:
+                continue
+            seen_pairs.add(pair)
+            new_edges.append({
+                "source": parent_nid,
+                "target": child_nid,
+                "relation": "contains",
+                "confidence": "EXTRACTED",
+                "confidence_score": 1.0,
+                "source_file": relpath,
+                "weight": 1.0,
+            })
+
+        # Create contains edges from heading to concept nodes in that section
+        # A concept node belongs to the nearest preceding heading
+        sorted_headings = sorted(all_headings, key=lambda h: h[1])
+        for n in nodes:
+            nid = n.get("id", "")
+            label = n.get("label", "")
+            start_line = n.get("start_line")
+            if not isinstance(start_line, int):
+                continue
+            # Find the nearest preceding heading
+            parent_heading_nid = None
+            for heading, h_lineno, h_level in reversed(sorted_headings):
+                if h_lineno <= start_line:
+                    parent_heading_nid = heading_nid_map.get(heading, _make_id(stem, heading))
+                    break
+            if parent_heading_nid and parent_heading_nid != nid:
+                pair = (parent_heading_nid, nid)
+                if pair not in seen_pairs:
+                    seen_pairs.add(pair)
+                    new_edges.append({
+                        "source": parent_heading_nid,
+                        "target": nid,
+                        "relation": "contains",
+                        "confidence": "EXTRACTED",
+                        "confidence_score": 0.9,
+                        "source_file": relpath,
+                        "weight": 0.9,
+                    })
+
+    return new_edges
+
+
+def _add_co_occurrence_edges(
+    doc_results: list[dict], doc_paths: list[Path], root: Path | None = None,
+) -> list[dict]:
+    """Add ``co_occurs_in`` edges between concept nodes in the same document.
+
+    Nodes appearing in the same paragraph get a co-occurrence edge with
+    weight=1.0.  Weight decays with paragraph distance:
+    weight = 1.0 / (1 + abs(paragraph_distance)).
+    Only creates edges between nodes from the same document.
+    """
+    new_edges: list[dict] = []
+    seen_pairs: set[tuple[str, str]] = set()
+
+    for result, path in zip(doc_results, doc_paths):
+        relpath = _doc_relpath(path, root)
+        nodes = result.get("nodes", [])
+        if len(nodes) < 2:
+            continue
+
+        # Compute paragraph index for each node based on start_line
+        # Paragraphs are separated by blank lines
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        lines = text.splitlines()
+
+        # Build line → paragraph_number map
+        para_map: dict[int, int] = {}
+        para_idx = 0
+        for i, line in enumerate(lines, start=1):
+            if i == 1 or (line.strip() == "" and i > 1):
+                # New paragraph starts after blank line (or at line 1)
+                if i > 1:
+                    para_idx += 1
+            para_map[i] = para_idx
+
+        # Get paragraph index for each node
+        node_paras: list[tuple[str, int]] = []  # (nid, paragraph)
+        for n in nodes:
+            nid = n.get("id", "")
+            start_line = n.get("start_line") or n.get("source_location", "")
+            # Parse line number
+            if isinstance(start_line, int):
+                lineno = start_line
+            elif isinstance(start_line, str) and start_line.startswith("L"):
+                try:
+                    lineno = int(start_line[1:])
+                except ValueError:
+                    continue
+            else:
+                continue
+            para = para_map.get(lineno, 0)
+            node_paras.append((nid, para))
+
+        # Create co-occurrence edges between all pairs in the same document
+        for i in range(len(node_paras)):
+            nid_i, para_i = node_paras[i]
+            for j in range(i + 1, len(node_paras)):
+                nid_j, para_j = node_paras[j]
+                if nid_i == nid_j:
+                    continue
+                # Sort pair to avoid duplicates
+                pair = tuple(sorted([nid_i, nid_j]))
+                if pair in seen_pairs:
+                    continue
+                dist = abs(para_i - para_j)
+                # Only create edges within a reasonable distance (same doc, ≤5 paragraphs)
+                if dist > 5:
+                    continue
+                weight = round(1.0 / (1 + dist), 2)
+                seen_pairs.add(pair)
+                new_edges.append({
+                    "source": pair[0],
+                    "target": pair[1],
+                    "relation": "co_occurs_in",
+                    "confidence": "INFERRED",
+                    "confidence_score": weight,
+                    "source_file": relpath,
+                    "weight": weight,
+                })
+
+    return new_edges
+
+
+def _resolve_markdown_link_references(
+    doc_results: list[dict], doc_paths: list[Path], root: Path | None = None,
+) -> list[dict]:
+    """Resolve Markdown ``[text](url)`` links into ``references`` edges.
+
+    Scans all document nodes' raws for Markdown links.  When the URL
+    resolves to another document in the corpus, creates a ``references``
+    edge from the source concept node to the target document's file-level
+    node (or the best matching concept node within the target document).
+    """
+    _MD_LINK = re.compile(r'\[([^\]]+)\]\(([^)]+)\)')
+
+    # Build file-level node ID map: relpath → nid
+    file_nid_map: dict[str, str] = {}
+    # Build label → nid map for intra-document concept matching
+    label_to_nid: dict[str, str] = {}
+    for result, path in zip(doc_results, doc_paths):
+        relpath = _doc_relpath(path, root)
+        stem = _doc_file_stem(path)
+        file_nid = _make_id(stem)
+        file_nid_map[relpath] = file_nid
+        # Also map by stem name for partial matches
+        file_nid_map[path.name] = file_nid
+        for n in result.get("nodes", []):
+            lbl = n.get("label", "")
+            nid = n.get("id", "")
+            if lbl and nid:
+                label_to_nid.setdefault(lbl, nid)
+
+    # Build a set of known document relative paths for fast lookup
+    known_relpaths = set(file_nid_map.keys())
+
+    new_edges: list[dict] = []
+    seen_pairs: set[tuple[str, str]] = set()
+
+    for result, path in zip(doc_results, doc_paths):
+        relpath = _doc_relpath(path, root)
+        for n in result.get("nodes", []):
+            nid = n.get("id", "")
+            raws_blocks = n.get("raws", [])
+            if not raws_blocks:
+                continue
+            raws_text = "\n".join(raws_blocks) if isinstance(raws_blocks, list) else str(raws_blocks)
+
+            for m in _MD_LINK.finditer(raws_text):
+                link_text = m.group(1).strip()
+                link_url = m.group(2).strip()
+
+                # Skip external URLs, anchors, and image links
+                if link_url.startswith(("http://", "https://", "#", "mailto:", "data:")):
+                    continue
+                # Strip anchor fragment
+                link_url = link_url.split("#")[0].split("?")[0]
+                if not link_url:
+                    continue
+
+                # Try to resolve the URL to a known document
+                target_nid = None
+                # Direct relative path match
+                if link_url in known_relpaths:
+                    target_nid = file_nid_map.get(link_url)
+                else:
+                    # Try matching by filename
+                    target_name = Path(link_url).name
+                    if target_name in file_nid_map:
+                        target_nid = file_nid_map[target_name]
+
+                # If no file-level match, try matching link text to a concept label
+                if target_nid is None and link_text in label_to_nid:
+                    target_nid = label_to_nid[link_text]
+
+                if target_nid is None or target_nid == nid:
+                    continue
+                if (nid, target_nid) in seen_pairs:
+                    continue
+                seen_pairs.add((nid, target_nid))
+                new_edges.append({
+                    "source": nid,
+                    "target": target_nid,
+                    "relation": "references",
+                    "confidence": "EXTRACTED",
+                    "confidence_score": 1.0,
+                    "source_file": relpath,
+                    "weight": 1.0,
+                })
+
+    return new_edges
+
+
 def merge_document_semantic_extracts(doc_extract: dict[str, Any], semantic_extract: dict[str, Any]) -> dict[str, Any]:
     """Merge deterministic doc symbols with semantic extraction.
 
@@ -3888,6 +4172,27 @@ def extract(paths: list[Path], cache_root: Path | None = None) -> dict:
             import logging
             logging.getLogger(__name__).warning("Document cross-reference resolution failed, skipping: %s", exc)
 
+        try:
+            md_link_edges = _resolve_markdown_link_references(doc_results, doc_paths, root)
+            all_edges.extend(md_link_edges)
+        except Exception as exc:
+            import logging
+            logging.getLogger(__name__).warning("Markdown link reference resolution failed, skipping: %s", exc)
+
+        try:
+            co_occurs_edges = _add_co_occurrence_edges(doc_results, doc_paths, root)
+            all_edges.extend(co_occurs_edges)
+        except Exception as exc:
+            import logging
+            logging.getLogger(__name__).warning("Co-occurrence edge creation failed, skipping: %s", exc)
+
+        try:
+            heading_edges = _add_heading_structure_edges(doc_results, doc_paths, root)
+            all_edges.extend(heading_edges)
+        except Exception as exc:
+            import logging
+            logging.getLogger(__name__).warning("Heading structure edge creation failed, skipping: %s", exc)
+
     return {
         "nodes": all_nodes,
         "edges": all_edges,

{graphify_vault-0.3.2 → graphify_vault-0.3.4}/graphify/serve.py

@@ -11,6 +11,7 @@ from pathlib import Path
 import networkx as nx
 from networkx.readwrite import json_graph
 from graphify.security import sanitize_label
+from graphify.cluster import label_communities
 
 
 def _resolve_graph_path(graph_path: str) -> str:
@@ -105,6 +106,12 @@ _TASK_MARKERS = (
     "relevant", "entry", "workflow", "flow", "path", "components", "component", "types",
 )
 
+_CONNECTION_MARKERS = (
+    "连接", "桥接", "关联", "中间", "之间", "关系",
+    "connect", "bridge", "link", "between", "relation", "intermediate",
+    "how does", "how do", "what connects", "what links", "what relates",
+)
+
 _STOP_TERMS = {
     "a", "an", "the", "and", "or", "but", "if", "then", "how", "what", "which", "where", "when",
     "why", "who", "whom", "whose", "should", "would", "could", "can", "do", "does", "did", "done",
@@ -483,6 +490,9 @@ def _classify_query_mode(question: str, terms: list[str] | None = None) -> str:
     identifier_like = bool(re.fullmatch(r"[A-Za-z_][A-Za-z0-9_\.]*", stripped))
     if identifier_like:
         return "entity"
+    # Connection queries: detect "connect/bridge/link/between" patterns
+    if any(marker in normalized for marker in _CONNECTION_MARKERS):
+        return "connection"
     if any(marker in question for marker in _TASK_MARKERS[:10]) or any(marker in normalized for marker in _TASK_MARKERS[10:]):
         return "task"
     if len(terms) >= 4:
@@ -715,6 +725,91 @@ def _compute_hub_labels(G: nx.Graph) -> set[str]:
     return hub_labels
 
 
+def _compute_graph_degree_stats(G: nx.Graph) -> dict[str, float]:
+    """Compute degree statistics for adaptive threshold calculation.
+
+    Returns median_degree and mean_degree for use in adaptive penalties.
+    These replace hard-coded penalty values with graph-relative ones.
+    """
+    if G.number_of_nodes() == 0:
+        return {"median_degree": 1.0, "mean_degree": 1.0}
+    degrees = [G.degree(n) for n in G.nodes]
+    sorted_degrees = sorted(degrees)
+    n = len(sorted_degrees)
+    median_degree = sorted_degrees[n // 2] if n % 2 == 1 else (sorted_degrees[n // 2 - 1] + sorted_degrees[n // 2]) / 2
+    mean_degree = sum(degrees) / n
+    return {"median_degree": max(median_degree, 1.0), "mean_degree": max(mean_degree, 1.0)}
+
+
+def _adaptive_penalty_score(G: nx.Graph, node_id: str, base_penalty: float, degree_stats: dict[str, float]) -> float:
+    """Compute adaptive penalty based on node degree relative to graph statistics.
+
+    Instead of hard-coded penalties (e.g., score -= 5.0), we scale penalties
+    by the node's degree relative to the median degree. High-degree nodes
+    get full penalties (they are hubs — if they don't match discriminative
+    terms, they are almost certainly irrelevant), while low-degree nodes
+    get reduced penalties (they may be specific but under-connected).
+
+    base_penalty: the maximum penalty to apply (e.g., 5.0 for non-discriminative)
+    """
+    degree = G.degree(node_id) if node_id in G else 0
+    median_degree = degree_stats.get("median_degree", 1.0)
+    # Scale penalty: high-degree nodes get full penalty, low-degree get reduced
+    # degree >= median: penalty = base_penalty * 1.0
+    # degree << median: penalty = base_penalty * 0.5
+    scale = min(1.0, max(0.5, degree / median_degree)) if median_degree > 0 else 1.0
+    return base_penalty * scale
+
+
+def _adaptive_threshold(scores: list[float], min_threshold: float = 1.0) -> float:
+    """Find adaptive threshold using elbow detection.
+
+    Instead of hard-coded threshold = top_score * 0.65, we find the "elbow"
+    in the score distribution - the point where scores start dropping rapidly.
+    This naturally adapts to different query result distributions.
+    """
+    if not scores:
+        return min_threshold
+    if len(scores) <= 2:
+        return max(scores[0] * 0.65, min_threshold)
+
+    # Sort scores descending
+    sorted_scores = sorted(scores, reverse=True)
+
+    # Find elbow: point with maximum second derivative (curvature)
+    # Simple approach: find where score drop exceeds average drop
+    drops = [sorted_scores[i] - sorted_scores[i + 1] for i in range(len(sorted_scores) - 1)]
+    if not drops:
+        return max(sorted_scores[0] * 0.65, min_threshold)
+
+    avg_drop = sum(drops) / len(drops)
+
+    # Find first index where drop exceeds 1.5x average
+    for i, drop in enumerate(drops):
+        if drop > avg_drop * 1.5 and i > 0:
+            # Threshold is the score at the elbow point (before the big drop)
+            return max(sorted_scores[i], min_threshold)
+
+    # No clear elbow found, use percentile-based threshold
+    return max(sorted_scores[len(sorted_scores) // 3], min_threshold)
+
+
+def _adaptive_community_quota(top_k: int, num_communities_in_graph: int) -> int:
+    """Compute adaptive community quota for seed diversity.
+
+    Instead of hard-coded community_quota = max(top_k // 2, 2), we scale
+    based on the number of communities in the graph. More communities
+    means we need more seeds per community to achieve coverage.
+    """
+    if num_communities_in_graph <= 2:
+        return max(top_k // 2, 2)
+    # Scale quota: more communities → smaller quota per community
+    # but ensure at least 2 seeds per community for diversity
+    base_quota = max(top_k // 2, 2)
+    scale = min(1.0, max(0.5, 3.0 / num_communities_in_graph))
+    return max(int(base_quota * scale), 1)
+
+
 def _parse_god_labels_from_report(report_text: str) -> set[str]:
     """Parse god node labels from GRAPH_REPORT.md text.
 
@@ -878,6 +973,124 @@ def _relation_family_weight(relation: str, confidence: str = "") -> float:
     return base + confidence_bonus
 
 
+def _connection_query(G: nx.Graph, question: str, terms: list[str], hub_labels: set[str] | None = None, god_labels: set[str] | None = None) -> dict[str, object]:
+    """Handle connection/bridge queries: find paths between concept clusters.
+
+    Strategy:
+    1. Find seeds from different communities (cross-domain seeds)
+    2. Compute shortest paths between cross-community seed pairs
+    3. Identify bridge nodes (nodes appearing on multiple paths)
+    4. Return bridge concepts + paths + neighbor summaries
+    """
+    # Find seeds with community diversity emphasis
+    seeds = _select_seed_nodes(G, question, terms, top_k=7, hub_labels=hub_labels, god_labels=god_labels)
+    if not seeds:
+        return {
+            "question": question,
+            "query_mode": "connection",
+            "terms": terms,
+            "bridges": [],
+            "paths": [],
+            "text": "No matching nodes found for connection query.",
+        }
+
+    # Group seeds by community
+    seed_by_community: dict[int, list[dict]] = {}
+    for seed in seeds:
+        cid = G.nodes.get(seed["node_id"], {}).get("community")
+        if cid is not None:
+            seed_by_community.setdefault(cid, []).append(seed)
+
+    # Need at least 2 communities for a connection query
+    if len(seed_by_community) < 2:
+        # Fall back to regular task query
+        return None  # Signal to caller to use task mode
+
+    # Find cross-community seed pairs and compute shortest paths
+    paths: list[dict] = []
+    bridge_counter: dict[str, int] = {}  # node_id -> count of paths it appears on
+    community_pairs = []
+    communities = list(seed_by_community.keys())
+    for i in range(len(communities)):
+        for j in range(i + 1, len(communities)):
+            community_pairs.append((communities[i], communities[j]))
+
+    for cid_a, cid_b in community_pairs[:6]:  # Limit to 6 pairs for performance
+        seeds_a = seed_by_community[cid_a]
+        seeds_b = seed_by_community[cid_b]
+        # Try shortest path between best seed from each community
+        for sa in seeds_a[:2]:
+            for sb in seeds_b[:2]:
+                try:
+                    path = nx.shortest_path(G, sa["node_id"], sb["node_id"])
+                except (nx.NetworkXNoPath, nx.NodeNotFound):
+                    continue
+                if len(path) < 2:
+                    continue
+                # Record path
+                path_labels = [G.nodes[n].get("label", n) for n in path]
+                path_relations = []
+                for k in range(len(path) - 1):
+                    edge = _edge_payload(G, path[k], path[k + 1])
+                    path_relations.append(edge.get("relation", ""))
+                paths.append({
+                    "from": path_labels[0],
+                    "to": path_labels[-1],
+                    "from_community": cid_a,
+                    "to_community": cid_b,
+                    "path": path_labels,
+                    "relations": path_relations,
+                    "length": len(path) - 1,
+                })
+                # Count bridge nodes (intermediate nodes on paths)
+                for node_id in path[1:-1]:  # Exclude endpoints
+                    bridge_counter[node_id] = bridge_counter.get(node_id, 0) + 1
+
+    # Identify bridge nodes: appear on multiple paths
+    bridges: list[dict] = []
+    for node_id, count in sorted(bridge_counter.items(), key=lambda x: -x[1]):
+        if count < 1:
+            continue
+        label = G.nodes[node_id].get("label", node_id)
+        degree = G.degree(node_id)
+        # Get neighbor summary
+        neighbors = list(G.neighbors(node_id))
+        neighbor_labels = [G.nodes[n].get("label", n) for n in neighbors[:8]]
+        neighbor_communities = {G.nodes[n].get("community") for n in neighbors if G.nodes[n].get("community") is not None}
+        bridges.append({
+            "node_id": node_id,
+            "label": label,
+            "degree": degree,
+            "path_count": count,
+            "neighbor_count": len(neighbors),
+            "neighbor_communities": len(neighbor_communities),
+            "sample_neighbors": neighbor_labels,
+        })
+
+    # Build text summary
+    text_parts = [f"Connection query: {question}"]
+    if bridges:
+        text_parts.append(f"\nBridge concepts ({len(bridges)}):")
+        for b in bridges[:5]:
+            text_parts.append(f"  - {b['label']} (appears on {b['path_count']} paths, connects {b['neighbor_communities']} communities)")
+    if paths:
+        text_parts.append(f"\nPaths found: {len(paths)}")
+        for p in paths[:3]:
+            text_parts.append(f"  {p['from']} --[{', '.join(p['relations'])}]--> {p['to']} (length {p['length']})")
+            if len(p['path']) > 2:
+                text_parts.append(f"    via: {' -> '.join(p['path'][1:-1])}")
+
+    return {
+        "question": question,
+        "query_mode": "connection",
+        "terms": terms,
+        "seeds": [{"node_id": s["node_id"], "label": s["label"], "seed_score": s["seed_score"]} for s in seeds],
+        "bridges": bridges[:10],
+        "paths": paths[:6],
+        "text": "\n".join(text_parts),
+    }
+
+
 def _select_seed_nodes(G: nx.Graph, question: str, terms: list[str], top_k: int = 5, hub_labels: set[str] | None = None, god_labels: set[str] | None = None) -> list[dict[str, object]]:
     scored_nodes = _score_nodes(G, terms)
     if not scored_nodes:
@@ -885,6 +1098,10 @@ def _select_seed_nodes(G: nx.Graph, question: str, terms: list[str], top_k: int
     base_scores = {nid: score for score, nid in scored_nodes}
     lexical_frontier = {nid for _, nid in scored_nodes[: max(top_k * 3, 12)]}
     compact_question = _normalize_query_text(question).replace(" ", "")
+    # Compute graph degree statistics for adaptive penalties
+    degree_stats = _compute_graph_degree_stats(G)
+    # Count communities for adaptive quota
+    all_communities = {G.nodes[n].get("community") for n in G.nodes if G.nodes[n].get("community") is not None}
     # Identify discriminative terms: those NOT matching generic/non-discriminative words.
     # Seeds that only match generic terms (e.g. "component") but miss
     # discriminative terms (e.g. "video") should be penalized.
@@ -933,26 +1150,29 @@ def _select_seed_nodes(G: nx.Graph, question: str, terms: list[str], top_k: int
             score += structural_support
             reasons.append("supported by nearby graph structure")
         if _is_noise_node(data, hub_labels):
-            score -= 3.0
+            score -= _adaptive_penalty_score(G, nid, 3.0, degree_stats)
         # Enum/config types (ending in Mode, Flag, Type, etc.) make poor
         # navigation seeds — users ask about components, not enum values.
         if re.match(r".*(Mode|Flag|Type|Options|Config|Style|Format|Encoding|Space|Completed|Started|Stopped|Paused|Unknown)$", label):
-            score -= 2.0
+            score -= _adaptive_penalty_score(G, nid, 2.0, degree_stats)
         # Penalize seeds that only match generic terms (e.g. "component")
         # but miss all discriminative terms (e.g. "video", "animation").
         if discriminative_compacts:
             label_spaced, label_compact = _normalized_label_forms(data.get("norm_label") or label)
             hits_discriminative = any(dt in label_compact or dt in label_spaced for dt in discriminative_compacts)
             if not hits_discriminative:
-                score -= 5.0
+                score -= _adaptive_penalty_score(G, nid, 5.0, degree_stats)
         if score > 0:
             scored.append((score, nid, reasons))
     scored.sort(key=lambda item: item[0], reverse=True)
     if not scored:
         return []
-    threshold = max(scored[0][0] * 0.65, 1.0)
+    # Adaptive threshold: find elbow in score distribution instead of hard-coded 0.65
+    all_scores = [s for s, _, _ in scored]
+    threshold = _adaptive_threshold(all_scores)
     seeds: list[dict[str, object]] = []
-    community_quota = max(top_k // 2, 2)
+    # Adaptive community quota: scale based on number of communities
+    community_quota = _adaptive_community_quota(top_k, len(all_communities))
     community_count: dict[int, int] = {}
     for score, nid, reasons in scored:
         if len(seeds) >= top_k:
@@ -1652,6 +1872,13 @@ def _query_graph(
     query_mode = _classify_query_mode(question, terms)
     # Compute hub labels from graph structure (replaces hard-coded _GENERIC_LABELS)
     hub_labels = _compute_hub_labels(G)
+    if query_mode == "connection":
+        result = _connection_query(G, question, terms, hub_labels=hub_labels, god_labels=god_labels)
+        if result is not None:
+            result["query_variants"] = query_texts
+            return result
+        # Fall back to task mode if not enough communities
+        query_mode = "task"
     if query_mode == "task":
         seeds = _select_seed_nodes(G, question, terms, top_k=5, hub_labels=hub_labels, god_labels=god_labels)
         if not seeds:
@@ -1707,7 +1934,9 @@ def _query_graph(
             "text": "No matching nodes found.",
         }
     top_score = scored[0][0]
-    threshold = top_score * 0.5
+    # Adaptive threshold: use elbow detection instead of hard-coded 0.5
+    all_scores = [s for s, _ in scored]
+    threshold = _adaptive_threshold(all_scores, min_threshold=0.5)
     start_nodes = [nid for s, nid in scored[:5] if s >= threshold]
     if not start_nodes:
         return {
@@ -2170,7 +2399,7 @@ def serve(graph_path: str = "graphify-out/graph.json", workspace: str | None = N
                 return {int(k): v for k, v in json.loads(labels_path.read_text(encoding="utf-8")).items()}
             except Exception:
                 pass
-        return {cid: f"Community {cid}" for cid in communities}
+        return label_communities(G, communities)
 
     @server.list_resources()
     async def list_resources() -> list[types.Resource]:

{graphify_vault-0.3.2 → graphify_vault-0.3.4}/graphify/watch.py

@@ -22,7 +22,7 @@ def _rebuild_code(watch_path: Path, *, follow_symlinks: bool = False) -> bool:
         from graphify.extract import extract
         from graphify.detect import detect
         from graphify.build import build_from_json
-        from graphify.cluster import cluster, score_all
+        from graphify.cluster import cluster, score_all, label_communities
         from graphify.analyze import god_nodes, surprising_connections, suggest_questions
         from graphify.report import generate
         from graphify.export import to_json, to_html
@@ -72,7 +72,7 @@ def _rebuild_code(watch_path: Path, *, follow_symlinks: bool = False) -> bool:
         cohesion = score_all(G, communities)
         gods = god_nodes(G)
         surprises = surprising_connections(G, communities)
-        labels = {cid: "Community " + str(cid) for cid in communities}
+        labels = label_communities(G, communities)
         questions = suggest_questions(G, communities, labels)
 
         out.mkdir(exist_ok=True)

{graphify_vault-0.3.2 → graphify_vault-0.3.4/graphify_vault.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphify_vault
-Version: 0.3.2
+Version: 0.3.4
 Summary: Fork of github.com/safishamsi/graphify with GRAPHIFY_WORKSPACE path resolution for distributed graph artifacts, same-label node merging, incremental build fixes, and local knowledge vault capabilities
 License: MIT License
         
@@ -56,6 +56,9 @@ Requires-Dist: tree-sitter-julia
 Requires-Dist: tree-sitter-verilog
 Provides-Extra: mcp
 Requires-Dist: mcp; extra == "mcp"
+Requires-Dist: deep-translator; extra == "mcp"
+Requires-Dist: pypdf; extra == "mcp"
+Requires-Dist: html2text; extra == "mcp"
 Provides-Extra: neo4j
 Requires-Dist: neo4j; extra == "neo4j"
 Provides-Extra: pdf
@@ -75,6 +78,7 @@ Requires-Dist: faster-whisper; extra == "video"
 Requires-Dist: yt-dlp; extra == "video"
 Provides-Extra: all
 Requires-Dist: mcp; extra == "all"
+Requires-Dist: deep-translator; extra == "all"
 Requires-Dist: neo4j; extra == "all"
 Requires-Dist: pypdf; extra == "all"
 Requires-Dist: html2text; extra == "all"

{graphify_vault-0.3.2 → graphify_vault-0.3.4}/graphify_vault.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 graphify = graphify.__main__:main
+gv = graphify.__main__:main

{graphify_vault-0.3.2 → graphify_vault-0.3.4}/graphify_vault.egg-info/requires.txt

@@ -24,6 +24,7 @@ tree-sitter-verilog
 
 [all]
 mcp
+deep-translator
 neo4j
 pypdf
 html2text
@@ -44,6 +45,9 @@ graspologic
 
 [mcp]
 mcp
+deep-translator
+pypdf
+html2text
 
 [neo4j]
 neo4j

{graphify_vault-0.3.2 → graphify_vault-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphify_vault"
-version = "0.3.2"
+version = "0.3.4"
 description = "Fork of github.com/safishamsi/graphify with GRAPHIFY_WORKSPACE path resolution for distributed graph artifacts, same-label node merging, incremental build fixes, and local knowledge vault capabilities"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -42,7 +42,7 @@ Repository = "https://github.com/gengwb/graphify"
 Issues = "https://github.com/gengwb/graphify/issues"
 
 [project.optional-dependencies]
-mcp = ["mcp"]
+mcp = ["mcp", "deep-translator", "pypdf", "html2text"]
 neo4j = ["neo4j"]
 pdf = ["pypdf", "html2text"]
 watch = ["watchdog"]
@@ -50,10 +50,11 @@ svg = ["matplotlib"]
 leiden = ["graspologic; python_version < '3.13'"]
 office = ["python-docx", "openpyxl"]
 video = ["faster-whisper", "yt-dlp"]
-all = ["mcp", "neo4j", "pypdf", "html2text", "watchdog", "graspologic; python_version < '3.13'", "python-docx", "openpyxl", "faster-whisper", "yt-dlp", "matplotlib"]
+all = ["mcp", "deep-translator", "neo4j", "pypdf", "html2text", "watchdog", "graspologic; python_version < '3.13'", "python-docx", "openpyxl", "faster-whisper", "yt-dlp", "matplotlib"]
 
 [project.scripts]
 graphify = "graphify.__main__:main"
+gv = "graphify.__main__:main"
 
 [tool.setuptools.packages.find]
 where = ["."]