kgmodule-utils 0.6.2__tar.gz → 0.7.0__tar.gz

{kgmodule_utils-0.6.2 → kgmodule_utils-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kgmodule-utils
-Version: 0.6.2
+Version: 0.7.0
 Summary: Shared types, graph store, semantic index, and pipeline base for the KGModule SDK
 License: Elastic-2.0
 License-File: LICENSE
@@ -17,6 +17,7 @@ Provides-Extra: semantic
 Provides-Extra: sqlite-vec
 Provides-Extra: synthesis
 Provides-Extra: synthesis-mflux
+Provides-Extra: viz
 Requires-Dist: httpx (>=0.27.0) ; extra == "synthesis"
 Requires-Dist: httpx (>=0.27.0) ; extra == "synthesis-mflux"
 Requires-Dist: lancedb (>=0.19.0) ; extra == "semantic"
@@ -26,6 +27,7 @@ Requires-Dist: openai (>=1.30.0) ; extra == "synthesis"
 Requires-Dist: openai (>=1.30.0) ; extra == "synthesis-mflux"
 Requires-Dist: pillow (>=10.0.0) ; extra == "synthesis"
 Requires-Dist: pillow (>=10.0.0) ; extra == "synthesis-mflux"
+Requires-Dist: pyvis (>=0.3.2) ; extra == "viz"
 Requires-Dist: rich (>=13.0.0) ; extra == "semantic"
 Requires-Dist: sentence-transformers (>=5.4.1) ; extra == "semantic"
 Requires-Dist: sqlite-vec (==0.1.9) ; extra == "sqlite-vec"
@@ -40,7 +42,7 @@ Description-Content-Type: text/markdown
 [![Version](https://img.shields.io/badge/version-0.6.2-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
 [![CI](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21364005.svg)](https://doi.org/10.5281/zenodo.21364005)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21387077.svg)](https://doi.org/10.5281/zenodo.21387077)
 
 # kgmodule-utils
 
@@ -319,11 +321,11 @@ poetry run pytest
 
 If you use kgmodule-utils in research or a project, please cite it:
 
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21364005.svg)](https://doi.org/10.5281/zenodo.21364005)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21387077.svg)](https://doi.org/10.5281/zenodo.21387077)
 
 **APA**
 
-> Suchanek, E. G. (2026). *kgmodule-utils: Shared SDK for the KGModule Knowledge-Graph Ecosystem* (Version 0.6.2) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.21364005
+> Suchanek, E. G. (2026). *kgmodule-utils: Shared SDK for the KGModule Knowledge-Graph Ecosystem* (Version 0.6.2) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.21387077
 
 **BibTeX**
 
@@ -335,7 +337,7 @@ If you use kgmodule-utils in research or a project, please cite it:
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/KG_utils},
-  doi       = {10.5281/zenodo.21364005},
+  doi       = {10.5281/zenodo.21387077},
 }
 ```
 

{kgmodule_utils-0.6.2 → kgmodule_utils-0.7.0}/README.md

@@ -4,7 +4,7 @@
 [![Version](https://img.shields.io/badge/version-0.6.2-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
 [![CI](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21364005.svg)](https://doi.org/10.5281/zenodo.21364005)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21387077.svg)](https://doi.org/10.5281/zenodo.21387077)
 
 # kgmodule-utils
 
@@ -283,11 +283,11 @@ poetry run pytest
 
 If you use kgmodule-utils in research or a project, please cite it:
 
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21364005.svg)](https://doi.org/10.5281/zenodo.21364005)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21387077.svg)](https://doi.org/10.5281/zenodo.21387077)
 
 **APA**
 
-> Suchanek, E. G. (2026). *kgmodule-utils: Shared SDK for the KGModule Knowledge-Graph Ecosystem* (Version 0.6.2) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.21364005
+> Suchanek, E. G. (2026). *kgmodule-utils: Shared SDK for the KGModule Knowledge-Graph Ecosystem* (Version 0.6.2) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.21387077
 
 **BibTeX**
 
@@ -299,7 +299,7 @@ If you use kgmodule-utils in research or a project, please cite it:
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/KG_utils},
-  doi       = {10.5281/zenodo.21364005},
+  doi       = {10.5281/zenodo.21387077},
 }
 ```
 

{kgmodule_utils-0.6.2 → kgmodule_utils-0.7.0}/pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "kgmodule-utils"
-version = "0.6.2"
+version = "0.7.0"
 description = "Shared types, graph store, semantic index, and pipeline base for the KGModule SDK"
 readme = "README.md"
 license = { text = "Elastic-2.0" }
@@ -37,6 +37,11 @@ semantic = [
     "torch>=2.5.1",
     "transformers>=4.40.0,<4.57",
 ]
+# Shared graph rendering (kg_utils.viz).  Kept out of the core so the
+# zero-dependency install stays zero-dependency.
+viz = [
+    "pyvis>=0.3.2",
+]
 # Exact pin: sqlite-vec is pre-1.0, breaking minors are possible. Prebuilt
 # wheels exist for macOS arm64 + Linux x86_64 (no compile step).
 sqlite-vec = [

{kgmodule_utils-0.6.2 → kgmodule_utils-0.7.0}/src/kg_utils/__init__.py

@@ -18,6 +18,10 @@ Sub-packages / modules:
                                     mflux-local | mflux-serve | openai (image).
     kg_utils.worker     — RunPod worker protocol helpers and WorkerClient for /runsync calls.
     kg_utils.retrieval  — Shared retrieval helpers: hit_to_dict, attach_content_by_sqlite.
+    kg_utils.analysis   — ScoreSet, load_scores, available_metrics: persisted
+                          centrality read back for ranking and visual encoding.
+    kg_utils.viz        — GraphTheme, TooltipSpec, build_graph_html, select_nodes:
+                          shared interactive graph rendering (needs the 'viz' extra).
 
 Optional extras
 ---------------
@@ -26,4 +30,4 @@ Optional extras
     pip install 'kgmodule-utils[synthesis-mflux]'  # + mflux (Apple Silicon local gen)
 """
 
-__version__ = "0.6.2"
+__version__ = "0.7.0"

kgmodule_utils-0.7.0/src/kg_utils/analysis/__init__.py

@@ -0,0 +1,19 @@
+"""Domain-agnostic analysis helpers shared by KG modules."""
+
+from kg_utils.analysis.scores import (
+    METRIC_TABLES,
+    MetricRef,
+    Scaler,
+    ScoreSet,
+    available_metrics,
+    load_scores,
+)
+
+__all__ = [
+    "METRIC_TABLES",
+    "MetricRef",
+    "Scaler",
+    "ScoreSet",
+    "available_metrics",
+    "load_scores",
+]

kgmodule_utils-0.7.0/src/kg_utils/analysis/scores.py

@@ -0,0 +1,329 @@
+"""
+Read persisted node-level metrics so renderers can encode them visually.
+
+KG modules that compute structural importance persist it to one of two tables:
+``centrality_scores`` (which also records the parameters used) or
+``node_metrics``.  Renderers read it back through this module to drive node size
+and opacity, so a graph shows what matters rather than only what kind each node
+is.
+
+This module closes that gap.  Both tables are already long-format and keyed by
+``(node_id, metric)``, which is exactly the shape needed to offer a metric
+selector, so no schema change is required.
+
+Neither table is part of the base graph schema — each is created lazily by its
+writer — so every function here treats a missing table, a missing database, or
+an unknown metric as "no data" rather than an error.  Renderers degrade to
+uniform sizing.
+
+Typical use::
+
+    metrics = available_metrics("graph.sqlite")
+    scores = load_scores("graph.sqlite", metrics[0].metric)
+    if scores:
+        radius = scores.scaled(node_id, 0.4, 2.0, default=0.7)
+        alpha = 0.35 + 0.65 * scores.percentile(node_id)
+"""
+
+from __future__ import annotations
+
+import math
+import sqlite3
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final, Literal
+
+__all__ = [
+    "METRIC_TABLES",
+    "MetricRef",
+    "ScoreSet",
+    "Scaler",
+    "available_metrics",
+    "load_scores",
+]
+
+#: Tables scanned for metrics, in preference order.  ``centrality_scores`` is
+#: first because its writer also records the parameters used.
+METRIC_TABLES: Final[tuple[str, ...]] = ("centrality_scores", "node_metrics")
+
+#: How a raw score is mapped onto a visual range.
+Scaler = Literal["log", "linear", "rank"]
+
+#: Guards ``log(0)`` when a metric's minimum equals one of its values.
+_LOG_EPSILON: Final[float] = 1e-9
+
+
+@dataclass(frozen=True)
+class MetricRef:
+    """A metric that exists in the database and can be loaded.
+
+    :param metric: Metric name as stored, e.g. ``"sir_pagerank"``.
+    :param table: Table the metric was found in.
+    :param count: Number of nodes carrying a score for this metric.
+    """
+
+    metric: str
+    table: str
+    count: int
+
+    @property
+    def label(self) -> str:
+        """Human-readable label for a selector widget.
+
+        :return: The metric name with underscores replaced by spaces.
+        """
+        return self.metric.replace("_", " ")
+
+
+@dataclass(frozen=True)
+class ScoreSet:
+    """Scores for one metric, with rank and percentile derived on load.
+
+    Ranks are computed from the loaded scores rather than read from the
+    ``rank`` column of ``centrality_scores``.  The stored rank reflects whatever
+    set the writer ranked, which may have been filtered or truncated; deriving
+    it here guarantees dense, consistent ranks over exactly the rows loaded, and
+    means ``node_metrics`` (which has no rank column) behaves identically.
+
+    :param metric: Metric name.
+    :param table: Table the scores came from.
+    :param scores: Mapping of node ID to raw score.
+    :param ranks: Mapping of node ID to 1-based rank, 1 being most central.
+    """
+
+    metric: str
+    table: str
+    scores: Mapping[str, float]
+    ranks: Mapping[str, int]
+
+    def __len__(self) -> int:
+        """Number of scored nodes.
+
+        :return: Count of nodes carrying a score.
+        """
+        return len(self.scores)
+
+    def __contains__(self, node_id: str) -> bool:
+        """Whether *node_id* carries a score.
+
+        :param node_id: Node ID to test.
+        :return: ``True`` if scored.
+        """
+        return node_id in self.scores
+
+    def score(self, node_id: str, default: float = 0.0) -> float:
+        """Raw score for *node_id*.
+
+        :param node_id: Node ID to look up.
+        :param default: Returned when the node is unscored.
+        :return: The stored score, or *default*.
+        """
+        return self.scores.get(node_id, default)
+
+    def rank(self, node_id: str) -> int | None:
+        """1-based rank for *node_id*, 1 being most central.
+
+        :param node_id: Node ID to look up.
+        :return: The rank, or ``None`` when the node is unscored.
+        """
+        return self.ranks.get(node_id)
+
+    def percentile(self, node_id: str, default: float = 0.0) -> float:
+        """Rank percentile in ``[0, 1]``, where ``1.0`` is the most central node.
+
+        Percentile is preferred over the raw score for opacity because
+        PageRank-style scores are heavily skewed — a linear map on raw values
+        leaves almost every node at the bottom of the range.
+
+        :param node_id: Node ID to look up.
+        :param default: Returned when the node is unscored.
+        :return: Percentile in ``[0, 1]``, or *default*.
+        """
+        rank = self.ranks.get(node_id)
+        if rank is None:
+            return default
+        n = len(self.ranks)
+        if n <= 1:
+            return 1.0
+        return (n - rank) / (n - 1)
+
+    def scaled(
+        self,
+        node_id: str,
+        lo: float,
+        hi: float,
+        *,
+        scaler: Scaler = "rank",
+        default: float | None = None,
+    ) -> float:
+        """Map *node_id*'s score onto the range ``[lo, hi]``.
+
+        ``"rank"`` is the default because it is the only option that uses the
+        full output range on real data.  Centrality scores are extremely
+        top-heavy — on a real code graph the median score was 1.2x the
+        minimum while the maximum was 58x it — and both alternatives handle that
+        badly.  ``"linear"`` collapses three quarters of the nodes onto the
+        floor; ``"log"`` overcorrects, because the single smallest value
+        stretches the bottom of the range far enough to push the bulk to ~0.73
+        of it.  Measured interquartile spread over an 8-42 px range was 1 px for
+        ``"linear"``, 4 px for ``"log"`` and 8 px for ``"rank"``.
+
+        The trade is that ``"rank"`` discards magnitude, implying visual
+        difference between scores that are nearly identical.  That is acceptable
+        for a node-link diagram, where size is a navigational affordance rather
+        than a measurement — callers wanting faithful magnitude should pass
+        ``"linear"`` and read exact values from the score itself.
+
+        :param node_id: Node ID to look up.
+        :param lo: Lower bound of the output range.
+        :param hi: Upper bound of the output range.
+        :param scaler: One of ``"rank"`` (default), ``"log"`` or ``"linear"``.
+        :param default: Returned when the node is unscored.  When ``None``, the
+            midpoint of ``[lo, hi]`` is used.
+        :return: A value within ``[lo, hi]``.
+        """
+        if node_id not in self.scores:
+            return (lo + hi) / 2.0 if default is None else default
+        return lo + self._fraction(node_id, scaler) * (hi - lo)
+
+    def _fraction(self, node_id: str, scaler: Scaler) -> float:
+        """Position of *node_id* within the metric's spread, in ``[0, 1]``.
+
+        :param node_id: Node ID to look up.
+        :param scaler: Scaling strategy.
+        :return: Fraction in ``[0, 1]``.
+        """
+        if scaler == "rank":
+            return self.percentile(node_id)
+
+        values = self.scores.values()
+        lo_val, hi_val = min(values), max(values)
+        if math.isclose(lo_val, hi_val):
+            # A degenerate metric carries no information; sit at the midpoint
+            # rather than pinning every node to one end of the range.
+            return 0.5
+
+        value = self.scores[node_id]
+        if scaler == "log":
+            shift = _LOG_EPSILON - lo_val
+            span = math.log(hi_val + shift) - math.log(lo_val + shift)
+            if span <= 0.0:
+                return 0.5
+            return (math.log(value + shift) - math.log(lo_val + shift)) / span
+        return (value - lo_val) / (hi_val - lo_val)
+
+
+def _table_exists(con: sqlite3.Connection, table: str) -> bool:
+    """Whether *table* exists in the connected database.
+
+    :param con: Open SQLite connection.
+    :param table: Table name.
+    :return: ``True`` when the table is present.
+    """
+    row = con.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (table,)
+    ).fetchone()
+    return row is not None
+
+
+def _connect(db_path: str | Path) -> sqlite3.Connection | None:
+    """Open *db_path* read-only, or return ``None`` when it does not exist.
+
+    A plain :func:`sqlite3.connect` would *create* a missing database, which
+    would silently produce an empty graph rather than a clear "not built yet".
+
+    :param db_path: Path to the graph database.
+    :return: An open connection, or ``None``.
+    """
+    path = Path(db_path)
+    if not path.is_file():
+        return None
+    try:
+        return sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+    except sqlite3.Error:
+        return None
+
+
+def available_metrics(db_path: str | Path) -> list[MetricRef]:
+    """List every metric present in the database.
+
+    Metrics are returned in table preference order (``centrality_scores`` before
+    ``node_metrics``), then by descending coverage.  A metric name appearing in
+    both tables yields two entries, distinguished by :attr:`MetricRef.table`.
+
+    :param db_path: Path to the graph database.
+    :return: Available metrics; empty when the database or both tables are
+        absent.
+    """
+    con = _connect(db_path)
+    if con is None:
+        return []
+
+    found: list[MetricRef] = []
+    try:
+        for table in METRIC_TABLES:
+            if not _table_exists(con, table):
+                continue
+            rows = con.execute(
+                f"SELECT metric, COUNT(*) FROM {table} GROUP BY metric"  # noqa: S608
+            ).fetchall()
+            found.extend(
+                MetricRef(metric=metric, table=table, count=count)
+                for metric, count in rows
+                if count
+            )
+    except sqlite3.Error:
+        return []
+    finally:
+        con.close()
+
+    order = {table: i for i, table in enumerate(METRIC_TABLES)}
+    found.sort(key=lambda ref: (order.get(ref.table, 99), -ref.count, ref.metric))
+    return found
+
+
+def load_scores(
+    db_path: str | Path,
+    metric: str,
+    *,
+    table: str | None = None,
+) -> ScoreSet | None:
+    """Load all scores for *metric*.
+
+    :param db_path: Path to the graph database.
+    :param metric: Metric name to load.
+    :param table: Restrict the lookup to one table.  When ``None``, the tables
+        in :data:`METRIC_TABLES` are tried in order and the first with rows for
+        *metric* wins.
+    :return: A :class:`ScoreSet`, or ``None`` when the metric is not present.
+    """
+    con = _connect(db_path)
+    if con is None:
+        return None
+
+    tables = (table,) if table else METRIC_TABLES
+    try:
+        for name in tables:
+            if name is None or not _table_exists(con, name):
+                continue
+            rows = con.execute(
+                f"SELECT node_id, score FROM {name} WHERE metric = ?",  # noqa: S608
+                (metric,),
+            ).fetchall()
+            if not rows:
+                continue
+            scores = {node_id: float(score) for node_id, score in rows}
+            ranks = {
+                node_id: i
+                for i, (node_id, _) in enumerate(
+                    sorted(scores.items(), key=lambda kv: (-kv[1], kv[0])), start=1
+                )
+            }
+            return ScoreSet(metric=metric, table=name, scores=scores, ranks=ranks)
+    except sqlite3.Error:
+        return None
+    finally:
+        con.close()
+
+    return None

kgmodule_utils-0.7.0/src/kg_utils/viz/__init__.py

@@ -0,0 +1,33 @@
+"""Shared graph visualisation for KG modules.
+
+Requires the ``viz`` extra::
+
+    pip install 'kgmodule-utils[viz]'
+
+Domain differences are supplied as data — a :class:`GraphTheme` naming the
+domain's kinds and relations, and a :class:`TooltipSpec` naming the fields worth
+showing — so every module shares one rendering implementation.
+"""
+
+from kg_utils.viz.graph_html import (
+    CENTRALITY_MIN_OPACITY,
+    CENTRALITY_SIZE_RANGE,
+    SEED_FRACTION,
+    build_graph_html,
+    select_nodes,
+)
+from kg_utils.viz.theme import GraphTheme, KindStyle, with_alpha
+from kg_utils.viz.tooltip import TooltipRow, TooltipSpec
+
+__all__ = [
+    "CENTRALITY_MIN_OPACITY",
+    "CENTRALITY_SIZE_RANGE",
+    "SEED_FRACTION",
+    "GraphTheme",
+    "KindStyle",
+    "TooltipRow",
+    "TooltipSpec",
+    "build_graph_html",
+    "select_nodes",
+    "with_alpha",
+]

kgmodule_utils-0.7.0/src/kg_utils/viz/graph_html.py

@@ -0,0 +1,412 @@
+"""
+Render a knowledge graph as a self-contained interactive HTML page.
+
+One implementation shared by every KG module.  Domain differences arrive as
+data: a :class:`~kg_utils.viz.theme.GraphTheme` naming the domain's kinds and
+relations, and a :class:`~kg_utils.viz.tooltip.TooltipSpec` naming the fields
+worth showing.  A plain callable can replace the spec when a domain needs markup
+the spec cannot express.
+
+The output inlines vis-network, so the page opens from ``file://`` and survives
+being embedded in a ``srcdoc`` iframe — both of which pyvis's default
+``cdn_resources="local"`` breaks, silently, by emitting relative asset paths.
+
+Requires the ``viz`` extra::
+
+    pip install 'kgmodule-utils[viz]'
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from collections.abc import Callable, Mapping, Sequence
+from pathlib import Path
+from typing import Any, Final
+
+from kg_utils.viz.theme import GraphTheme, with_alpha
+from kg_utils.viz.tooltip import TooltipSpec
+
+__all__ = [
+    "CENTRALITY_MIN_OPACITY",
+    "CENTRALITY_SIZE_RANGE",
+    "SEED_FRACTION",
+    "build_graph_html",
+    "select_nodes",
+]
+
+#: Node diameter range in pixels when a metric drives sizing.
+CENTRALITY_SIZE_RANGE: Final[tuple[int, int]] = (8, 42)
+
+#: Opacity floor for the least central node.  Never 0 — an invisible node is
+#: indistinguishable from a missing one.
+CENTRALITY_MIN_OPACITY: Final[float] = 0.35
+
+#: Share of the node budget spent on seeds; the rest goes to their neighbours.
+SEED_FRACTION: Final[int] = 4
+
+#: Border colour for nodes the caller asked to highlight.
+_HIGHLIGHT_COLOR: Final[str] = "#FFD700"
+
+_MAX_LABEL = 28
+
+_PHYSICS_OPTIONS: Final[dict[str, Any]] = {
+    "barnesHut": {
+        "gravitationalConstant": -8000,
+        "centralGravity": 0.3,
+        "springLength": 120,
+        "springConstant": 0.04,
+        "damping": 0.09,
+    },
+    "stabilization": {"iterations": 150},
+}
+
+
+def _describe(scores: Any, kept: Sequence[str], suffix: str) -> str:
+    """Summarise a selection for display above the graph.
+
+    Reporting how many kept nodes carry no score matters once neighbours are
+    pulled in by expansion: those are frequently unscored, and a reader should
+    not assume every node on screen was ranked.
+
+    :param scores: The active ``ScoreSet``.
+    :param kept: Node IDs that were kept.
+    :param suffix: Extra text describing the strategy.
+    :return: Human-readable description.
+    """
+    unscored = sum(1 for i in kept if scores.rank(i) is None)
+    tail = f" ({unscored} unscored)" if unscored else ""
+    return f"most central by {scores.metric}{suffix}{tail}"
+
+
+def select_nodes(
+    nodes: list[dict],
+    limit: int,
+    scores: Any | None,
+    mode: str = "central",
+    expand: Callable[[set[str], int], set[str]] | None = None,
+) -> tuple[list[dict], str]:
+    """Reduce *nodes* to at most *limit*, choosing which ones to keep.
+
+    A graph can only draw a few hundred nodes, so which ones survive the cap
+    decides what the reader actually sees.  Two strategies:
+
+    * ``"path"`` keeps the store's natural order.  Because that order is
+      contiguous by source, the result is well connected — but it is an
+      arbitrary slice, typically alphabetical.
+    * ``"central"`` seeds on the most central nodes and pulls in their graph
+      neighbours until the budget is spent.
+
+    Seeding *and expanding* rather than taking the top N is the important
+    detail.  The most central nodes are scattered, so keeping only them strands
+    most of them: measured on a 10k-node code graph at a cap of 150,
+    top-N-by-centrality left 47 nodes with no edge at all and halved the edge
+    count, producing a field of dots rather than a graph.
+
+    :param nodes: Candidate nodes, already filtered.
+    :param limit: Maximum number to keep.
+    :param scores: Active ``ScoreSet``, or ``None``.
+    :param mode: ``"central"`` or ``"path"``.
+    :param expand: Callable taking ``(seed_ids, hop)`` and returning the node IDs
+        reachable within that many hops.  Without it, ``"central"`` degrades to
+        top-N by centrality.
+    :return: The kept nodes and a short description of how they were chosen.
+    """
+    if len(nodes) <= limit:
+        return nodes, "all matching nodes"
+    if mode != "central" or scores is None:
+        return nodes[:limit], "first in store order"
+
+    by_id = {n["id"]: n for n in nodes}
+    ranked = sorted(by_id, key=lambda i: (scores.rank(i) is None, scores.rank(i) or 0, i))
+
+    if expand is None:
+        top = ranked[:limit]
+        return [by_id[i] for i in top], _describe(scores, top, "")
+
+    seed_count = max(1, limit // SEED_FRACTION)
+    seeds = set(ranked[:seed_count])
+    reachable = expand(seeds, 1) & by_id.keys()
+
+    kept: list[str] = list(ranked[:seed_count])
+    seen = set(kept)
+    for node_id in sorted(
+        reachable, key=lambda i: (scores.rank(i) is None, scores.rank(i) or 0, i)
+    ):
+        if len(kept) >= limit:
+            break
+        if node_id not in seen:
+            kept.append(node_id)
+            seen.add(node_id)
+    for node_id in ranked:
+        if len(kept) >= limit:
+            break
+        if node_id not in seen:
+            kept.append(node_id)
+            seen.add(node_id)
+
+    return [by_id[i] for i in kept], _describe(scores, kept, ", plus neighbours")
+
+
+def build_graph_html(
+    nodes: Sequence[Mapping[str, Any]],
+    edges: Sequence[Mapping[str, Any]],
+    *,
+    theme: GraphTheme,
+    tooltip: TooltipSpec | Callable[[Mapping[str, Any], str], str] | None = None,
+    scores: Any | None = None,
+    height: str = "620px",
+    physics: bool = True,
+    highlight_ids: set[str] | None = None,
+    label_field: str = "name",
+) -> str:
+    """Render *nodes* and *edges* as a self-contained interactive HTML page.
+
+    When *scores* is supplied, node diameter and opacity both encode the
+    metric's rank percentile.  Without it, diameter comes from the theme's
+    per-kind size and every node is fully opaque.
+
+    :param nodes: Node attribute mappings; each needs at least an ``id``.
+    :param edges: Edge mappings with ``src``, ``dst`` and ``rel`` keys.
+    :param theme: Visual vocabulary for this domain.
+    :param tooltip: A :class:`TooltipSpec`, or a callable taking
+        ``(node, color)`` and returning HTML.  ``None`` shows kind and name only.
+    :param scores: ``ScoreSet`` driving size and opacity, or ``None``.
+    :param height: CSS height for the canvas, e.g. ``"620px"``.
+    :param physics: Whether to run the Barnes-Hut simulation.
+    :param highlight_ids: Node IDs to mark with a gold border — query seeds,
+        search hits, whatever the caller wants to point at.
+    :param label_field: Node key used for the on-canvas label.
+    :return: A self-contained HTML document.
+    """
+    from pyvis.network import Network  # noqa: PLC0415 — keeps the viz extra optional
+
+    net = Network(
+        height=height,
+        width="100%",
+        bgcolor="#0e1117",
+        font_color="#e0e0e0",
+        directed=True,
+        notebook=False,
+        # pyvis defaults to cdn_resources="local", which emits *relative* asset
+        # paths plus a cdnjs fallback, and writes a lib/ directory into the
+        # working directory.  Relative paths cannot resolve inside a srcdoc
+        # iframe, so the graph renders only when cdnjs is reachable and fails
+        # silently with "vis is not defined" otherwise.  "in_line" inlines
+        # vis-network, making the page genuinely self-contained.
+        cdn_resources="in_line",
+    )
+    net.set_options(
+        json.dumps(
+            {
+                "physics": {"enabled": physics, **_PHYSICS_OPTIONS},
+                "edges": {
+                    "smooth": {"type": "dynamic"},
+                    "arrows": {"to": {"enabled": True, "scaleFactor": 0.6}},
+                    "font": {"size": 10, "color": "#aaaaaa"},
+                },
+                "interaction": {
+                    "hover": True,
+                    "tooltipDelay": 80,
+                    "navigationButtons": True,
+                    "keyboard": True,
+                },
+            }
+        )
+    )
+
+    highlight_ids = highlight_ids or set()
+    lo_size, hi_size = CENTRALITY_SIZE_RANGE
+    panel_data: dict[str, dict[str, Any]] = {}
+
+    for node in nodes:
+        node_id = node["id"]
+        style = theme.style_of(node)
+        color = style.color
+
+        label = str(node.get(label_field) or node_id)
+        if len(label) > _MAX_LABEL:
+            label = label[: _MAX_LABEL - 3] + "…"
+
+        if tooltip is None:
+            title = f"{node.get('kind', '')}: {label}"
+        elif isinstance(tooltip, TooltipSpec):
+            title = tooltip.render(node, color)
+        else:
+            title = tooltip(node, color)
+
+        if scores is None:
+            size: float = style.size
+            background = color
+        else:
+            size = scores.scaled(node_id, lo_size, hi_size, default=lo_size)
+            alpha = CENTRALITY_MIN_OPACITY + (1.0 - CENTRALITY_MIN_OPACITY) * scores.percentile(
+                node_id
+            )
+            background = with_alpha(color, alpha)
+
+        highlighted = node_id in highlight_ids
+        net.add_node(
+            node_id,
+            label=label,
+            title=title,
+            color={
+                "background": background,
+                "border": _HIGHLIGHT_COLOR if highlighted else color,
+                "highlight": {"background": color, "border": "#FFFFFF"},
+            },
+            shape=style.shape,
+            size=size,
+            borderWidth=3 if highlighted else 1,
+            font={"size": 11},
+        )
+        panel_data[node_id] = _panel_entry(node, color, tooltip, scores)
+
+    for edge in edges:
+        rel = str(edge.get("rel", ""))
+        net.add_edge(
+            edge["src"],
+            edge["dst"],
+            label=rel,
+            color=theme.relation_color(rel),
+            width=1.5,
+            title=rel,
+        )
+
+    with tempfile.NamedTemporaryFile(suffix=".html", delete=False, mode="w") as handle:
+        tmp_path = handle.name
+    try:
+        net.save_graph(tmp_path)
+        document = Path(tmp_path).read_text(encoding="utf-8")
+    finally:
+        os.unlink(tmp_path)
+
+    return document.replace("</body>", _panel_markup(panel_data) + "</body>")
+
+
+def _panel_entry(
+    node: Mapping[str, Any],
+    color: str,
+    tooltip: TooltipSpec | Callable[..., str] | None,
+    scores: Any | None,
+) -> dict[str, Any]:
+    """Build the click-panel payload for one node.
+
+    Driven by the same spec as the hover tooltip so the two never disagree.
+
+    :param node: Node attribute mapping.
+    :param color: Accent colour.
+    :param tooltip: The active tooltip spec, if it is a spec.
+    :param scores: Active ``ScoreSet``, used to include rank.
+    :return: JSON-serialisable panel entry.
+    """
+    spec = tooltip if isinstance(tooltip, TooltipSpec) else None
+    if spec is None:
+        title = str(node.get("name") or node["id"])
+        meta: list[str] = []
+        body = ""
+    else:
+        title = (
+            str(node.get(spec.title) or node.get("name") or node["id"])
+            if isinstance(spec.title, str)
+            else spec.title(node)
+        )
+        meta = [text for text in (row.render(node) for row in spec.rows) if text]
+        body = str(node.get(spec.body) or "").strip() if spec.body else ""
+
+    rank = scores.rank(node["id"]) if scores is not None else None
+    return {
+        "id": node["id"],
+        "kind": str(node.get("kind", "")),
+        "color": color,
+        "title": title,
+        "meta": meta,
+        "body": body,
+        "rank": rank,
+        "metric": getattr(scores, "metric", None) if scores is not None else None,
+    }
+
+
+def _panel_markup(panel_data: Mapping[str, Mapping[str, Any]]) -> str:
+    """Return the CSS, markup and script for the floating click-detail panel.
+
+    :param panel_data: Per-node payload keyed by node ID.
+    :return: HTML to inject before ``</body>``.
+    """
+    # The payload is embedded in a <script> block, so any "</script>" inside a
+    # node's text would terminate the block during HTML parsing and inject
+    # whatever followed.  Escaping the three characters that can start such a
+    # sequence keeps the JSON valid while making breakout impossible.
+    payload = (
+        json.dumps(panel_data, ensure_ascii=False)
+        .replace("<", "\\u003c")
+        .replace(">", "\\u003e")
+        .replace("&", "\\u0026")
+    )
+    return """
+<style>
+#kgviz-panel {
+  display: none; position: fixed; top: 12px; right: 12px; width: 340px;
+  max-height: 88vh; overflow-y: auto; background: #1e1e2e; border-radius: 10px;
+  box-shadow: 0 4px 24px rgba(0,0,0,0.6); z-index: 9999;
+  font-family: sans-serif; font-size: 13px; color: #e0e0e0;
+}
+#kgviz-panel-inner { padding: 14px 16px 16px 16px; }
+#kgviz-panel-close {
+  position: absolute; top: 8px; right: 10px; cursor: pointer; font-size: 18px;
+  color: #888; line-height: 1; background: none; border: none;
+}
+#kgviz-panel-close:hover { color: #fff; }
+#kgviz-panel-body {
+  background: #12121f; border: 1px solid #2a2a3e; border-radius: 6px;
+  padding: 8px 10px; font-family: monospace; font-size: 12px; color: #c9d1d9;
+  white-space: pre-wrap; word-break: break-word; margin-top: 8px;
+  max-height: 300px; overflow-y: auto;
+}
+</style>
+<div id="kgviz-panel">
+  <button id="kgviz-panel-close"
+          onclick="document.getElementById('kgviz-panel').style.display='none'">&#10005;</button>
+  <div id="kgviz-panel-inner">
+    <div id="kgviz-panel-badge"></div>
+    <div id="kgviz-panel-title" style="font-size:15px;font-weight:bold;margin:6px 0 2px 0;"></div>
+    <div id="kgviz-panel-meta" style="color:#888;font-size:11px;font-family:monospace;"></div>
+    <div id="kgviz-panel-id"
+         style="color:#444;font-size:10px;font-family:monospace;margin-top:2px;"></div>
+    <div id="kgviz-panel-body"></div>
+  </div>
+</div>
+<script>
+(function () {
+  var NODE_DATA = __KGVIZ_PAYLOAD__;
+  function esc(s) {
+    return String(s == null ? "" : s)
+      .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  }
+  function show(nodeId) {
+    var n = NODE_DATA[nodeId];
+    if (!n) { return; }
+    document.getElementById("kgviz-panel-badge").innerHTML =
+      "<span style='background:" + n.color + ";color:#fff;border-radius:4px;" +
+      "padding:1px 7px;font-size:11px;font-weight:bold;'>" + esc(n.kind) + "</span>";
+    document.getElementById("kgviz-panel-title").textContent = n.title;
+    var meta = (n.meta || []).slice();
+    if (n.rank) { meta.push(n.metric + " rank " + n.rank); }
+    document.getElementById("kgviz-panel-meta").textContent = meta.join("  ·  ");
+    document.getElementById("kgviz-panel-id").textContent = n.id;
+    var body = document.getElementById("kgviz-panel-body");
+    body.textContent = n.body || "";
+    body.style.display = n.body ? "block" : "none";
+    document.getElementById("kgviz-panel").style.display = "block";
+  }
+  function attach() {
+    if (typeof network === "undefined") { window.setTimeout(attach, 120); return; }
+    network.on("click", function (params) {
+      if (params.nodes && params.nodes.length) { show(params.nodes[0]); }
+    });
+  }
+  attach();
+})();
+</script>
+""".replace("__KGVIZ_PAYLOAD__", payload)

kgmodule_utils-0.7.0/src/kg_utils/viz/theme.py

@@ -0,0 +1,135 @@
+"""
+Declarative visual vocabulary for graph renderers.
+
+A :class:`GraphTheme` says how one domain's node kinds and edge relations should
+look.  It is data, not code: each KG module constructs one and hands it to the
+renderer, so all modules share a single rendering implementation while naming
+their own kinds.  ``code`` has modules and functions, ``doc`` has sections and
+chunks, ``meta`` has compounds and reactions — only ``id``, ``kind`` and
+``name`` are common to all of them.
+
+Typical use::
+
+    THEME = GraphTheme(
+        kinds={
+            "document": KindStyle("#4A90D9", shape="box", size=18),
+            "chunk": KindStyle("#27AE60", shape="ellipse"),
+        },
+        fallback=KindStyle("#95A5A6", shape="triangle"),
+        relations={"CONTAINS": "#BDC3C7", "SIMILAR_TO": "#E74C3C"},
+    )
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Final
+
+__all__ = ["GraphTheme", "KindStyle", "with_alpha"]
+
+#: Used when a theme names no relation colour and declares no fallback.
+DEFAULT_RELATION_COLOR: Final[str] = "#888888"
+
+
+@dataclass(frozen=True)
+class KindStyle:
+    """How one node kind is drawn.
+
+    :param color: Fill colour as ``#RRGGBB``.  The renderer converts this to
+        ``rgba()`` when a centrality metric drives opacity, so six-digit hex is
+        required for fading to work.
+    :param shape: vis.js node shape — ``dot``, ``box``, ``ellipse``,
+        ``diamond``, ``triangle``, ``star``, and so on.
+    :param size: Node diameter in pixels when no metric is driving size.
+    :param radius: Node radius in world units for 3-D renderers.  Ignored by the
+        HTML renderer; carried here so one theme can serve both.
+    """
+
+    color: str
+    shape: str = "dot"
+    size: int = 12
+    radius: float = 0.7
+
+
+@dataclass(frozen=True)
+class GraphTheme:
+    """The full visual vocabulary for one knowledge-graph domain.
+
+    :param kinds: Node kind to :class:`KindStyle`.
+    :param fallback: Style for kinds absent from *kinds*.  Every graph
+        eventually meets a kind nobody planned for, and silently dropping those
+        nodes is worse than drawing them grey.
+    :param relations: Edge relation to colour.
+    :param relation_fallback: Colour for relations absent from *relations*.
+    :param resolve_kind: Optional hook mapping a node to a *render* kind that
+        need not exist in the store — for example drawing underscore-prefixed
+        functions differently.  Receives the whole node dict.  Must return a key
+        present in *kinds*, or anything else to get *fallback*.
+    """
+
+    kinds: Mapping[str, KindStyle]
+    fallback: KindStyle
+    relations: Mapping[str, str] = field(default_factory=dict)
+    relation_fallback: str = DEFAULT_RELATION_COLOR
+    resolve_kind: Callable[[Mapping[str, Any]], str] | None = None
+
+    def kind_of(self, node: Mapping[str, Any]) -> str:
+        """Return the render kind for *node*.
+
+        :param node: Node attribute mapping.
+        :return: A kind name, which may be a render-only kind from
+            :attr:`resolve_kind` rather than one the store knows about.
+        """
+        if self.resolve_kind is not None:
+            return self.resolve_kind(node)
+        return str(node.get("kind", ""))
+
+    def style_of(self, node: Mapping[str, Any]) -> KindStyle:
+        """Return the style for *node*, falling back rather than raising.
+
+        :param node: Node attribute mapping.
+        :return: The matching :class:`KindStyle`, or :attr:`fallback`.
+        """
+        return self.kinds.get(self.kind_of(node), self.fallback)
+
+    def style_for_kind(self, kind: str) -> KindStyle:
+        """Return the style for a kind name.
+
+        :param kind: Kind name.
+        :return: The matching :class:`KindStyle`, or :attr:`fallback`.
+        """
+        return self.kinds.get(kind, self.fallback)
+
+    def relation_color(self, relation: str) -> str:
+        """Return the colour for an edge relation.
+
+        :param relation: Relation name.
+        :return: Hex colour string.
+        """
+        return self.relations.get(relation, self.relation_fallback)
+
+
+def with_alpha(hex_color: str, alpha: float) -> str:
+    """Convert ``#RRGGBB`` to an ``rgba()`` string at the given opacity.
+
+    vis.js accepts CSS colour strings for node backgrounds, so opacity is
+    expressed by converting the palette hex rather than by compositing against
+    the canvas background.
+
+    :param hex_color: Colour in ``#RRGGBB`` form, with or without the leading
+        ``#``.
+    :param alpha: Opacity in ``[0, 1]``; values outside the range are clamped.
+    :return: An ``rgba(r, g, b, a)`` string, or *hex_color* unchanged when it is
+        not a six-digit hex colour — a CSS keyword should degrade to an opaque
+        colour rather than crash a render.
+    """
+    raw = hex_color.lstrip("#")
+    if len(raw) != 6:
+        return hex_color
+    try:
+        r, g, b = (int(raw[i : i + 2], 16) for i in (0, 2, 4))
+    except ValueError:
+        return hex_color
+    a = min(1.0, max(0.0, alpha))
+    return f"rgba({r}, {g}, {b}, {a:.3f})"

kgmodule_utils-0.7.0/src/kg_utils/viz/tooltip.py

@@ -0,0 +1,119 @@
+"""
+Declarative hover-tooltip specification for graph renderers.
+
+Node schemas diverge sharply between KG domains — code nodes carry
+``qualname``/``module_path``/``lineno``, document nodes carry
+``title``/``file_path``/``char_start``, metabolic nodes carry
+``formula``/``ec_number``.  Only ``id``, ``kind`` and ``name`` are universal.
+
+A :class:`TooltipSpec` lets each domain name its own fields while the renderer
+keeps one implementation of the markup, so the viewers stay visually consistent
+without every module writing its own HTML.  When a domain needs markup the spec
+cannot express, the renderer also accepts a plain callable instead — see
+``build_graph_html``.
+"""
+
+from __future__ import annotations
+
+import html
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["TooltipRow", "TooltipSpec"]
+
+
+@dataclass(frozen=True)
+class TooltipRow:
+    """One metadata line beneath the tooltip's title.
+
+    :param value: Either a node-dict key, or a callable taking the whole node
+        and returning display text.  The callable form exists for values that
+        span several fields, such as a line range built from ``lineno`` and
+        ``end_lineno``.
+    :param prefix: Short text or emoji placed before the value.
+    :param skip_if_empty: Drop the row when the value is empty or ``None``.
+        Almost always what you want — a tooltip full of blank labels is worse
+        than a short one.
+    """
+
+    value: str | Callable[[Mapping[str, Any]], str]
+    prefix: str = ""
+    skip_if_empty: bool = True
+
+    def render(self, node: Mapping[str, Any]) -> str:
+        """Resolve this row against *node*.
+
+        :param node: Node attribute mapping.
+        :return: Display text, empty when the row should be dropped.
+        """
+        if isinstance(self.value, str):
+            raw = node.get(self.value)
+            text = "" if raw is None else str(raw)
+        else:
+            text = self.value(node) or ""
+        text = text.strip()
+        if not text and self.skip_if_empty:
+            return ""
+        return f"{self.prefix}{text}" if self.prefix else text
+
+
+@dataclass(frozen=True)
+class TooltipSpec:
+    """How to build a node's hover tooltip from its fields.
+
+    :param title: Node key holding the bold heading, or a callable.
+    :param rows: Metadata lines shown under the heading, joined with separators.
+    :param body: Node key holding free text — a docstring, chunk text or
+        description — rendered in a monospaced block below a rule.
+    :param body_lines: Maximum body lines before truncation.
+    :param max_width: Tooltip width in pixels.
+    """
+
+    title: str | Callable[[Mapping[str, Any]], str] = "name"
+    rows: Sequence[TooltipRow] = field(default_factory=tuple)
+    body: str | None = None
+    body_lines: int = 8
+    max_width: int = 400
+
+    def render(self, node: Mapping[str, Any], color: str) -> str:
+        """Build the tooltip HTML for *node*.
+
+        :param node: Node attribute mapping.
+        :param color: Accent colour for the kind badge and left border.
+        :return: An HTML string suitable for a pyvis node ``title``.
+        """
+        kind = html.escape(str(node.get("kind", "")))
+        if isinstance(self.title, str):
+            title_text = str(node.get(self.title) or node.get("name") or node.get("id", ""))
+        else:
+            title_text = self.title(node)
+        title = html.escape(title_text)
+
+        rendered = [r.render(node) for r in self.rows]
+        meta = "  ·  ".join(html.escape(r) for r in rendered if r)
+        meta_html = f"<br><span style='color:#888;font-size:11px;'>{meta}</span>" if meta else ""
+
+        body_html = ""
+        if self.body:
+            raw = str(node.get(self.body) or "").strip()
+            if raw:
+                lines = raw.splitlines()
+                shown = [html.escape(line) for line in lines[: self.body_lines]]
+                ellipsis = "…" if len(lines) > self.body_lines else ""
+                body_html = (
+                    "<hr style='border:0;border-top:1px solid #444;margin:6px 0;'>"
+                    "<div style='font-family:monospace;font-size:11px;color:#ccc;"
+                    "white-space:pre-wrap;'>" + "\n".join(shown) + ellipsis + "</div>"
+                )
+
+        return (
+            f"<div style='font-family:sans-serif;font-size:12px;"
+            f"background:#1e1e2e;color:#e0e0e0;padding:10px 14px;"
+            f"border-radius:8px;border-left:4px solid {color};"
+            f"max-width:{self.max_width}px;'>"
+            f"<span style='background:{color};color:#fff;border-radius:4px;"
+            f"padding:1px 7px;font-size:11px;font-weight:bold;'>{kind}</span>"
+            f"&nbsp;&nbsp;<b style='font-size:13px;'>{title}</b>"
+            f"{meta_html}{body_html}</div>"
+        )