pycode-kg 0.21.2__tar.gz → 0.22.0__tar.gz

{pycode_kg-0.21.2 → pycode_kg-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.21.2
+Version: 0.22.0
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -24,7 +24,7 @@ Requires-Dist: PyQt5 (>=5.15.0) ; extra == "viz3d"
 Requires-Dist: click (>=8.1.0,<9)
 Requires-Dist: detect-secrets (>=1.5.0) ; extra == "all"
 Requires-Dist: detect-secrets (>=1.5.0) ; extra == "dev"
-Requires-Dist: kgmodule-utils[semantic,sqlite-vec,viz] (>=0.9.0)
+Requires-Dist: kgmodule-utils[semantic,viz3d] (>=0.11.0)
 Requires-Dist: markdown (>=3.6) ; extra == "all"
 Requires-Dist: markdown (>=3.6) ; extra == "viz3d"
 Requires-Dist: mcp (>=1.0.0,<2)
@@ -45,21 +45,20 @@ Requires-Dist: pytest-cov (>=5.0.0) ; extra == "all"
 Requires-Dist: pytest-cov (>=5.0.0) ; extra == "dev"
 Requires-Dist: pyvis (>=0.3.2) ; extra == "all"
 Requires-Dist: pyvis (>=0.3.2) ; extra == "viz"
-Requires-Dist: pyvista[jupyter] (>=0.44.0) ; extra == "all"
-Requires-Dist: pyvista[jupyter] (>=0.44.0) ; extra == "viz3d"
+Requires-Dist: pyvista (>=0.44.0) ; extra == "all"
+Requires-Dist: pyvista (>=0.44.0) ; extra == "viz3d"
 Requires-Dist: pyvistaqt (>=0.11.0) ; extra == "all"
 Requires-Dist: pyvistaqt (>=0.11.0) ; extra == "viz3d"
 Requires-Dist: rich (>=14.3.3,<15)
 Requires-Dist: ruff (>=0.4.0) ; extra == "all"
 Requires-Dist: ruff (>=0.4.0) ; extra == "dev"
-Requires-Dist: safetensors (>=0.5.0)
 Requires-Dist: sentence-transformers (>=5.4.1)
+Requires-Dist: sqlite-vec (==0.1.9)
 Requires-Dist: streamlit (>=1.56.0) ; extra == "all"
 Requires-Dist: streamlit (>=1.56.0) ; extra == "viz"
 Requires-Dist: torch (>=2.5.1)
 Requires-Dist: trame-vtk (>=2.0.0) ; extra == "all"
 Requires-Dist: trame-vtk (>=2.0.0) ; extra == "viz3d"
-Requires-Dist: transformers (>=5.5.0,<6)
 Requires-Dist: ty (>=0.0.41) ; extra == "all"
 Requires-Dist: ty (>=0.0.41) ; extra == "dev"
 Project-URL: Homepage, https://github.com/Flux-Frontiers/pycode_kg
@@ -73,7 +72,7 @@ Description-Content-Type: text/markdown
 
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
-[![Version](https://img.shields.io/badge/version-0.21.2-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.22.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
 [![CI](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/pycode_kg/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/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
@@ -244,7 +243,7 @@ src/pycode_kg/
 └── viz3d_timeline.py                # Metric history timeline
 ```
 
-The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.19.0.md](docs/analysis_v0.19.0.md), produced (of course) by `pycodekg analyze` against this very repo.
+The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.22.0.md](docs/analysis_v0.22.0.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -270,17 +269,17 @@ If you use PyCodeKG in your research or project, please cite it:
 
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
 
-> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.21.2) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19834777
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.22.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
 
 ```bibtex
 @software{suchanek_pycode_kg,
   author    = {Suchanek, Eric G.},
   title     = {{PyCodeKG}: A Knowledge Graph for Python Codebases},
-  version   = {0.21.2},
+  version   = {0.22.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},
-  doi       = {10.5281/zenodo.19834777},
+  doi       = {10.5281/zenodo.19737993},
 }
 ```
 
@@ -300,5 +299,5 @@ If you use PyCodeKG in your research or project, please cite it:
 
 ---
 
-*Built for Python developers and AI agents that work alongside them — egs · Last updated July 2026*
+*Built for Python developers and AI agents that work alongside them — egs · Last updated August 2026*
 

{pycode_kg-0.21.2 → pycode_kg-0.22.0}/README.md

@@ -5,7 +5,7 @@
 
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
-[![Version](https://img.shields.io/badge/version-0.21.2-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.22.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
 [![CI](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/pycode_kg/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/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
@@ -176,7 +176,7 @@ src/pycode_kg/
 └── viz3d_timeline.py                # Metric history timeline
 ```
 
-The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.19.0.md](docs/analysis_v0.19.0.md), produced (of course) by `pycodekg analyze` against this very repo.
+The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.22.0.md](docs/analysis_v0.22.0.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -202,17 +202,17 @@ If you use PyCodeKG in your research or project, please cite it:
 
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
 
-> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.21.2) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19834777
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.22.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
 
 ```bibtex
 @software{suchanek_pycode_kg,
   author    = {Suchanek, Eric G.},
   title     = {{PyCodeKG}: A Knowledge Graph for Python Codebases},
-  version   = {0.21.2},
+  version   = {0.22.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},
-  doi       = {10.5281/zenodo.19834777},
+  doi       = {10.5281/zenodo.19737993},
 }
 ```
 
@@ -232,4 +232,4 @@ If you use PyCodeKG in your research or project, please cite it:
 
 ---
 
-*Built for Python developers and AI agents that work alongside them — egs · Last updated July 2026*
+*Built for Python developers and AI agents that work alongside them — egs · Last updated August 2026*

{pycode_kg-0.21.2 → pycode_kg-0.22.0}/pyproject.toml

@@ -1,7 +1,7 @@
 # pyproject.toml — PyCodeKG package configuration (PEP 621)
 #
 # Author: Eric G. Suchanek, PhD
-# Last Revision: 2026-07-29
+# Last Revision: 2026-08-11
 #
 # Build system : Poetry 2.x with PEP 621 [project] table
 #
@@ -70,7 +70,7 @@ torch = [
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.21.2"
+version = "0.22.0"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"
@@ -101,11 +101,32 @@ dependencies = [
     "numpy>=1.24.0",
     "pandas>=2.0.0",
     "rich>=14.3.3,<15",
-    "safetensors>=0.5.0",
     "sentence-transformers>=5.4.1",
+    # Core, not optional: kg.py hard-codes vector_backend="sqlite-vec", so every
+    # build/query path goes through kg_utils.vector_backend.SqliteVecBackend,
+    # which imports sqlite_vec at connect time. Exact pin — sqlite-vec is pre-1.0
+    # and breaking minors ship under 0.x; kgmodule-utils pins the same ==0.1.9.
+    # Declared here rather than pulled via kgmodule-utils[sqlite-vec] so the
+    # requirement is visible in this project's own metadata (doc-kg 0.20.0 does
+    # the same).
+    "sqlite-vec==0.1.9",
+    # Kept direct even though `[semantic]` carries the same `>=2.5.1`: the
+    # `[tool.poetry.dependencies]` block above routes linux torch to the CPU-only
+    # index, and that enrichment only applies to a dependency this project
+    # declares itself. Dropping it here would pull the ~3.4G CUDA wheel back in.
     "torch>=2.5.1",
-    "transformers>=5.5.0,<6",
-    "kgmodule-utils[semantic,sqlite-vec,viz]>=0.9.0",
+    # `[semantic]` is safe again as of kgmodule-utils 0.10.0, which moved
+    # `lancedb` out into its own `[lancedb]` extra. It now carries numpy, rich,
+    # sentence-transformers, sqlite-vec, torch and transformers under the same
+    # constraints used here, so `transformers` needs no direct entry.
+    # `[viz]` stays off: kg_utils.viz imports pyvis lazily, so it would force
+    # pyvis into every bare install when it belongs in this project's own `viz`
+    # extra.
+    # `[viz3d]` is the shared 3-D layout engine behind `pycode_kg.layout3d`.
+    # Its only dependency is numpy, which `[semantic]` already pulls, so it adds
+    # nothing to the install — it just declares what layout3d actually imports.
+    # Unlike `[viz]`, there is no pyvis to leak into a bare install.
+    "kgmodule-utils[semantic,viz3d]>=0.11.0",
 ]
 
 [project.optional-dependencies]
@@ -127,7 +148,7 @@ viz3d = [
     "markdown>=3.6",
     "param>=2.0.0",
     "PyQt5>=5.15.0",
-    "pyvista[jupyter]>=0.44.0",
+    "pyvista>=0.44.0",
     "pyvistaqt>=0.11.0",
     "trame-vtk>=2.0.0",
 ]
@@ -149,7 +170,7 @@ all = [
     "PyQt5>=5.15.0",
     "pytest>=8.0.0",
     "pytest-cov>=5.0.0",
-    "pyvista[jupyter]>=0.44.0",
+    "pyvista>=0.44.0",
     "pyvistaqt>=0.11.0",
     "pyvis>=0.3.2",
     "ruff>=0.4.0",
@@ -158,6 +179,27 @@ all = [
     "ty>=0.0.41",
 ]
 
+# Maintainer tooling, not a dependency of this package. `.mcp.json` serves a
+# `dockg` MCP server from `.venv/bin/dockg`, so the CLI has to be in this repo's
+# environment — but nothing under src/ imports doc_kg, and declaring it as a real
+# dependency would put it in the published wheel for every consumer.
+#
+# A Poetry group is the right shape: it is locked and installable but never
+# written into wheel metadata, so `pip install pycode-kg` is unaffected.
+#
+#   poetry install --with kg      # gets the dockg CLI into .venv/bin
+#   poetry install                # default — the group is optional, skipped
+#
+# `kg` is the fleet-wide name for this group so there is one command to remember;
+# contents are per-repo and minimal, covering only what that repo actually
+# invokes. Safe to lock because doc-kg keeps its own pycode-kg in a group too, so
+# the published metadata on either side has no cycle for the resolver to chase.
+[tool.poetry.group.kg]
+optional = true
+
+[tool.poetry.group.kg.dependencies]
+doc-kg = ">=0.21.1"
+
 [project.urls]
 Homepage = "https://github.com/Flux-Frontiers/pycode_kg"
 Repository = "https://github.com/Flux-Frontiers/pycode_kg"
@@ -190,7 +232,13 @@ target-version = "py312"
 # Vendored agent scratch dirs (Claude Code skills, Codex) — not project code.
 # The pre-commit hook's exclude can't cover these (it runs with
 # pass_filenames: false), so the exclusion must live here.
-extend-exclude = [".claude", ".agents", ".codex"]
+extend-exclude = [".claude", ".agents", ".codex", "*.md"]
+# ruff 0.16 formats Python code blocks inside Markdown as stable behaviour
+# (0.15 gates it behind preview), so `ruff format --check .` starts rewriting
+# prose docs the moment the lock resolves 0.16 — a failure that looks unrelated
+# to whatever change triggered the relock. Doc snippets are illustrative and
+# often deliberately aligned, so keep them out of the formatter's reach.
+# doc_kg and ftree_kg carry the same exclusion.
 
 [tool.ruff.lint]
 # B023, BLE001, PLC0415 replace the retired pylint hook's cell-var-from-loop,

{pycode_kg-0.21.2 → pycode_kg-0.22.0}/src/pycode_kg/__init__.py

@@ -32,7 +32,7 @@ KGModule SDK (build new domain KGs)::
     from pycode_kg import KGModule, KGExtractor, PyCodeKGExtractor, NodeSpec, EdgeSpec
 """
 
-__version__ = "0.21.2"
+__version__ = "0.22.0"
 __author__ = "Eric G. Suchanek, PhD"
 
 # Low-level primitives (locked v0 contract)

{pycode_kg-0.21.2 → pycode_kg-0.22.0}/src/pycode_kg/analysis/bridge.py

@@ -4,7 +4,7 @@ Measures module interaction complexity: how many unique modules each module call
 For well-modularized codebases, identifies orchestrator and hub modules.
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-07-28 22:44:43
+Last Revision: 2026-08-03 11:37:06
 License: Elastic 2.0
 """
 

{pycode_kg-0.21.2 → pycode_kg-0.22.0}/src/pycode_kg/analysis/centrality.py

@@ -12,7 +12,7 @@ Public API:
     - :func:`aggregate_module_scores` — roll node scores up to module level.
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-07-28 22:44:43
+Last Revision: 2026-08-03 11:37:06
 """
 
 from __future__ import annotations

{pycode_kg-0.21.2 → pycode_kg-0.22.0}/src/pycode_kg/analysis/framework_detector.py

@@ -3,7 +3,7 @@ Framework Detector for PyCodeKG.
 Identifies repo-defining abstractions using centrality and cross-module signals.
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-07-28 22:44:43
+Last Revision: 2026-08-03 11:37:06
 License: Elastic 2.0
 """
 

{pycode_kg-0.21.2 → pycode_kg-0.22.0}/src/pycode_kg/cli/cmd_hooks.py

@@ -6,7 +6,7 @@ CLI command for installing PyCodeKG git hooks:
   install-hooks — install the pre-commit snapshot hook into .git/hooks/
 
   Author: Eric G. Suchanek, PhD
-  Last Revision: 2026-07-29 15:21:32
+  Last Revision: 2026-08-03 11:37:06
 """
 
 from __future__ import annotations

pycode_kg-0.22.0/src/pycode_kg/layout3d.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""
+PyCodeKG's 3-D layout bindings over the shared layout engine.
+
+The engine itself lives in :mod:`kg_utils.viz3d`, shared with every other KG
+module — GutenbergKG was already importing it from here, paying a full
+``pycode-kg`` dependency for five symbols that have nothing to do with parsing
+Python.  What stays here is the part that is genuinely specific to a *code*
+graph: which node kinds occupy which Z level, which comes from
+:mod:`pycode_kg.theme`.
+
+Everything is re-exported so existing callers do not need to know where the
+implementation moved.
+
+The Fibonacci utilities (``fibonacci_sphere``, ``fibonacci_annulus``) are
+adapted from *repo_vis* ``pkg_visualizer/utility.py``
+(Eric G. Suchanek, PhD — https://github.com/Suchanek/repo_vis).
+
+Author: Eric G. Suchanek, PhD
+"""
+
+from __future__ import annotations
+
+from kg_utils.viz3d import (
+    AlliumLayout,
+    Layout3D,
+    LayoutEdge,
+    LayoutNode,
+    fibonacci_annulus,
+    fibonacci_sphere,
+    golden_spiral_2d,
+)
+from kg_utils.viz3d import FunnelLayout as _SharedFunnelLayout
+
+from pycode_kg import theme
+
+__all__ = [
+    "AlliumLayout",
+    "FunnelLayout",
+    "Layout3D",
+    "LayoutEdge",
+    "LayoutNode",
+    "fibonacci_annulus",
+    "fibonacci_sphere",
+    "golden_spiral_2d",
+]
+
+
+class FunnelLayout(_SharedFunnelLayout):
+    """Funnel layout stratified by *code* node kind.
+
+    The shared engine takes the kind→Z-level mapping as an argument, because
+    only the domain knows its own hierarchy — modules at the bottom, then
+    classes, then functions and methods, with symbol stubs on top is a fact
+    about Python code, not about knowledge graphs.  This subclass supplies
+    that mapping from :mod:`pycode_kg.theme`, so the layout engine, the 3-D
+    viewer and the 2-D explorer keep sharing one definition.
+
+    Unknown kinds land on the symbol level, matching
+    :func:`pycode_kg.theme.resolve_kind`, which collapses anything the palette
+    does not recognise to ``symbol``.
+
+    :param layer_gap: Vertical distance between adjacent layers.
+    :param node_spacing: Spacing multiplier — larger spreads layers out more.
+    :param kwargs: Forwarded to :class:`kg_utils.viz3d.FunnelLayout`; the
+        theme-derived defaults are only applied to keys left unset.
+    """
+
+    def __init__(
+        self,
+        layer_gap: float = 12.0,
+        node_spacing: float = 2.0,
+        **kwargs,
+    ) -> None:
+        """Initialise layout parameters, defaulting the maps from the theme.
+
+        :param layer_gap: Vertical separation between layers.
+        :param node_spacing: Controls minimum gap between node surfaces.
+        :param kwargs: Overrides forwarded to the shared layout.
+        """
+        kwargs.setdefault("zlevels", theme.KIND_ZLEVEL)
+        kwargs.setdefault("level_sizes", theme.LEVEL_NODE_SIZE)
+        kwargs.setdefault("default_level", theme.KIND_ZLEVEL[theme.UNKNOWN_KIND])
+        super().__init__(layer_gap=layer_gap, node_spacing=node_spacing, **kwargs)

{pycode_kg-0.21.2 → pycode_kg-0.22.0}/src/pycode_kg/pycodekg.py

@@ -23,7 +23,7 @@ No persistence, no embeddings, no LLMs—just pure AST extraction. Integration w
 vector databases and semantic search happens downstream.
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-07-28 22:44:43
+Last Revision: 2026-08-03 11:37:06
 """
 
 from __future__ import annotations

{pycode_kg-0.21.2 → pycode_kg-0.22.0}/src/pycode_kg/snapshots.py

@@ -35,7 +35,7 @@ Usage
 >>> prev = mgr.get_previous(tree_hash)
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-07-28
+Last Revision: 2026-08-03
 
 License: Elastic 2.0
 """

pycode_kg-0.21.2/src/pycode_kg/layout3d.py

@@ -1,476 +0,0 @@
-#!/usr/bin/env python3
-"""
-layout3d.py — Pluggable 3-D layout engine for the PyCodeKG knowledge graph.
-
-Provides an abstract :class:`Layout3D` base class and two concrete
-implementations:
-
-- :class:`AlliumLayout`: Each module is rendered as a Giant Allium plant
-  (a vertical stem with a Fibonacci-sphere "head" of classes and functions).
-  Modules are arranged in a Fibonacci annulus in the XY plane.
-
-- :class:`FunnelLayout`: Node kind determines the Z level (modules at
-  the bottom, classes above, functions/methods at the top).  XY positions
-  are spread via a golden-angle spiral within each layer.
-
-The Fibonacci utilities (``fibonacci_sphere``, ``fibonacci_annulus``) are
-adapted from *repo_vis* ``pkg_visualizer/utility.py``
-(Eric G. Suchanek, PhD — https://github.com/Suchanek/repo_vis).
-
-Author: Eric G. Suchanek, PhD
-"""
-
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from dataclasses import dataclass
-
-import numpy as np
-
-from pycode_kg import theme
-
-# ---------------------------------------------------------------------------
-# Fibonacci spatial utilities  (adapted from repo_vis/pkg_visualizer/utility.py)
-# ---------------------------------------------------------------------------
-
-
-def fibonacci_sphere(
-    samples: int,
-    radius: float = 1.0,
-    center: np.ndarray | None = None,
-) -> list[np.ndarray]:
-    """
-    Distribute *samples* points uniformly on a sphere using the Fibonacci spiral.
-
-    Adapted from ``utility.fibonacci_sphere`` in *repo_vis*.
-
-    :param samples: Number of points to generate.
-    :param radius: Sphere radius.
-    :param center: Centre of the sphere (default: origin).
-    :return: List of 3-D coordinate arrays.
-    """
-    if center is None:
-        center = np.zeros(3)
-    if samples <= 0:
-        return []
-    if samples == 1:
-        return [center + radius * np.array([0.0, 0.0, 1.0])]
-
-    phi = np.pi * (3.0 - np.sqrt(5.0))  # golden angle in radians
-    points: list[np.ndarray] = []
-    for i in range(samples):
-        y = 1.0 - (i / float(samples - 1)) * 2.0
-        r_at_y = np.sqrt(max(0.0, 1.0 - y * y))
-        theta = phi * i
-        x = np.cos(theta) * r_at_y
-        z = np.sin(theta) * r_at_y
-        points.append(center + radius * np.array([x, y, z]))
-    return points
-
-
-def fibonacci_annulus(
-    samples: int,
-    inner_radius: float = 1.0,
-    outer_radius: float = 2.0,
-    center: np.ndarray | None = None,
-    z_thickness: float = 0.2,
-) -> list[np.ndarray]:
-    """
-    Distribute *samples* points in a flat annular ring in the XY plane.
-
-    A small Z jitter (``z_thickness``) adds visual depth when non-zero.
-    Adapted from ``utility.fibonacci_annulus`` in *repo_vis*.
-
-    :param samples: Number of points to generate.
-    :param inner_radius: Inner radius of the annulus.
-    :param outer_radius: Outer radius of the annulus.
-    :param center: Centre of the annulus (default: origin).
-    :param z_thickness: Half-range of Z jitter applied to each point.
-    :return: List of 3-D coordinate arrays.
-    """
-    if center is None:
-        center = np.zeros(3)
-    if samples <= 0:
-        return []
-    if samples == 1:
-        mid = (inner_radius + outer_radius) / 2.0
-        return [center + np.array([mid, 0.0, 0.0])]
-
-    phi = np.pi * (3.0 - np.sqrt(5.0))
-    r_range = outer_radius - inner_radius
-    r_step = r_range / max(samples - 1, 1)
-    rng = np.random.default_rng(42)  # deterministic jitter seed
-
-    points: list[np.ndarray] = []
-    for i in range(samples):
-        r = inner_radius + i * r_step
-        theta = phi * i
-        x = np.cos(theta) * r
-        y = np.sin(theta) * r
-        z = (rng.random() * 2.0 - 1.0) * z_thickness
-        points.append(center + np.array([x, y, z]))
-    return points
-
-
-def _golden_spiral_2d(
-    samples: int,
-    radius: float = 1.0,
-    center: np.ndarray | None = None,
-    z: float = 0.0,
-) -> list[np.ndarray]:
-    """
-    Place *samples* points in the XY plane using a golden-angle disc spiral.
-
-    :param samples: Number of points.
-    :param radius: Outer radius of the disc.
-    :param center: XY centre (Z component ignored; overridden by *z*).
-    :param z: Fixed Z coordinate for all output points.
-    :return: List of 3-D coordinate arrays.
-    """
-    if center is None:
-        center = np.zeros(3)
-    if samples <= 0:
-        return []
-
-    phi = np.pi * (3.0 - np.sqrt(5.0))
-    points: list[np.ndarray] = []
-    for i in range(samples):
-        r = radius * np.sqrt(i / max(samples - 1, 1))
-        theta = phi * i
-        x = r * np.cos(theta)
-        y = r * np.sin(theta)
-        points.append(center + np.array([x, y, z]))
-    return points
-
-
-# ---------------------------------------------------------------------------
-# Data transfer objects
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class LayoutNode:
-    """
-    Thin wrapper around a node dict from :class:`~pycode_kg.store.GraphStore`.
-
-    :param id: Stable node identifier (e.g. ``mod:src/foo.py``).
-    :param kind: Node kind — ``module``, ``class``, ``function``, ``method``,
-        or ``symbol``.
-    :param name: Short name of the node.
-    :param module_path: Source module path (may be ``None`` for symbol stubs).
-    :param docstring: Raw docstring text (may be ``None``).
-    :param lineno: First source line number (may be ``None``).
-    :param end_lineno: Last source line number (may be ``None``).
-    """
-
-    id: str
-    kind: str
-    name: str
-    module_path: str | None = None
-    docstring: str | None = None
-    lineno: int | None = None
-    end_lineno: int | None = None
-
-    @classmethod
-    def from_dict(cls, d: dict) -> LayoutNode:
-        """Construct from a GraphStore node dict.
-
-        :param d: Dict with keys ``id``, ``kind``, ``name``, etc.
-        :return: New :class:`LayoutNode`.
-        """
-        return cls(
-            id=d["id"],
-            kind=d["kind"],
-            name=d["name"],
-            module_path=d.get("module_path"),
-            docstring=d.get("docstring"),
-            lineno=d.get("lineno"),
-            end_lineno=d.get("end_lineno"),
-        )
-
-    @property
-    def line_count(self) -> int:
-        """Approximate source size in lines (0 if unknown).
-
-        :return: ``end_lineno - lineno`` or 0.
-        """
-        if self.lineno and self.end_lineno:
-            return max(0, self.end_lineno - self.lineno)
-        return 0
-
-
-@dataclass
-class LayoutEdge:
-    """
-    Thin wrapper around an edge dict from :class:`~pycode_kg.store.GraphStore`.
-
-    :param src: Source node ID.
-    :param rel: Relation type — ``CONTAINS``, ``CALLS``, ``IMPORTS``,
-        ``INHERITS``.
-    :param dst: Destination node ID.
-    """
-
-    src: str
-    rel: str
-    dst: str
-
-    @classmethod
-    def from_dict(cls, d: dict) -> LayoutEdge:
-        """Construct from a GraphStore edge dict.
-
-        :param d: Dict with keys ``src``, ``rel``, ``dst``.
-        :return: New :class:`LayoutEdge`.
-        """
-        return cls(src=d["src"], rel=d["rel"], dst=d["dst"])
-
-
-# ---------------------------------------------------------------------------
-# Abstract base
-# ---------------------------------------------------------------------------
-
-
-class Layout3D(ABC):
-    """
-    Abstract base class for 3-D graph layout strategies.
-
-    Subclasses implement :meth:`compute` to assign a 3-D position to every
-    node, returning a ``{node_id: np.ndarray([x, y, z])}`` mapping that the
-    :class:`~pycode_kg.viz3d.KGViz3D` renderer consumes.
-    """
-
-    @abstractmethod
-    def compute(
-        self,
-        nodes: list[LayoutNode],
-        edges: list[LayoutEdge],
-    ) -> dict[str, np.ndarray]:
-        """
-        Compute 3-D positions for all *nodes*.
-
-        :param nodes: All nodes in the graph.
-        :param edges: All edges in the graph (used to derive hierarchy).
-        :return: Mapping from node ID to ``[x, y, z]`` position.
-        """
-        ...
-
-
-# ---------------------------------------------------------------------------
-# AlliumLayout
-# ---------------------------------------------------------------------------
-
-
-class AlliumLayout(Layout3D):
-    """
-    Allium-plant layout: each module is visualised as a Giant Allium flower.
-
-    Spatial structure:
-
-    - **Stem base** — module node sits at XY position in a Fibonacci annulus
-      at ``Z = 0``.
-    - **Head** — classes and top-level functions are distributed on a
-      Fibonacci sphere centred at the stem apex (``Z = stem_height``).
-      Head radius scales with ``sqrt(n_children)``.
-    - **Florets** — methods orbit their parent class on a smaller Fibonacci
-      sphere, slightly above the head.
-    - **Orphans** — nodes with no CONTAINS parent cluster on a small sphere
-      at the origin.
-
-    Multiple module-alliums are arranged in a Fibonacci annulus in the XY
-    plane so they are evenly spaced regardless of count.
-
-    Inspired by :class:`GiantAllium` in *repo_vis/pkg_visualizer/plants3d.py*.
-
-    :param stem_height: Height of each allium stem (Z offset of the head).
-    :param base_head_radius: Minimum radius for the Fibonacci sphere head.
-    :param method_orbit_radius: Base radius for method sub-spheres.
-    :param annulus_inner_radius: Inner radius of the module placement ring.
-    :param annulus_outer_radius: Minimum outer radius (auto-scaled for large graphs).
-    """
-
-    def __init__(
-        self,
-        stem_height: float = 8.0,
-        base_head_radius: float = 2.0,
-        method_orbit_radius: float = 0.8,
-        annulus_inner_radius: float = 8.0,
-        annulus_outer_radius: float = 20.0,
-    ) -> None:
-        """Initialise layout parameters.
-
-        :param stem_height: Vertical height of each allium stem.
-        :param base_head_radius: Minimum allium head sphere radius.
-        :param method_orbit_radius: Base orbit radius for methods.
-        :param annulus_inner_radius: Inner radius for module ring placement.
-        :param annulus_outer_radius: Minimum outer radius for module ring.
-        """
-        self.stem_height = stem_height
-        self.base_head_radius = base_head_radius
-        self.method_orbit_radius = method_orbit_radius
-        self.annulus_inner_radius = annulus_inner_radius
-        self.annulus_outer_radius = annulus_outer_radius
-
-    def compute(
-        self,
-        nodes: list[LayoutNode],
-        edges: list[LayoutEdge],
-    ) -> dict[str, np.ndarray]:
-        """
-        Compute allium-plant 3-D positions for all nodes.
-
-        :param nodes: All nodes in the graph.
-        :param edges: All edges (``CONTAINS`` used to derive hierarchy).
-        :return: Mapping from node ID to ``[x, y, z]`` position.
-        """
-        # Build CONTAINS hierarchy: child_id -> parent_id, parent_id -> [child_ids]
-        parent: dict[str, str] = {}
-        children: dict[str, list[str]] = {}
-        for e in edges:
-            if e.rel == "CONTAINS":
-                parent[e.dst] = e.src
-                children.setdefault(e.src, []).append(e.dst)
-
-        node_by_id: dict[str, LayoutNode] = {n.id: n for n in nodes}
-        positions: dict[str, np.ndarray] = {}
-
-        # Module nodes form the allium stems
-        modules = [n for n in nodes if n.kind == "module"]
-        if not modules:
-            # Fallback: treat nodes without a CONTAINS parent as pseudo-modules
-            modules = [n for n in nodes if n.id not in parent]
-
-        n_mods = len(modules)
-        inner = self.annulus_inner_radius
-        # Scale outer radius so stems don't crowd each other
-        outer = max(self.annulus_outer_radius, inner + np.sqrt(n_mods) * 4.0)
-
-        mod_positions = fibonacci_annulus(
-            n_mods,
-            inner_radius=inner,
-            outer_radius=outer,
-            center=np.zeros(3),
-            z_thickness=0.0,  # flat ring — alliums stand vertically
-        )
-
-        for mod_node, mod_pos in zip(modules, mod_positions):
-            positions[mod_node.id] = np.array(mod_pos)
-            stem_apex = np.array([mod_pos[0], mod_pos[1], self.stem_height])
-
-            # Direct children (classes, top-level functions)
-            direct_ids = children.get(mod_node.id, [])
-            direct = [node_by_id[cid] for cid in direct_ids if cid in node_by_id]
-            n_direct = len(direct)
-            if not direct:
-                continue
-
-            # Head radius scales with child count
-            head_r = self.base_head_radius + np.sqrt(n_direct) * 0.4
-            head_positions = fibonacci_sphere(n_direct, radius=head_r, center=stem_apex)
-
-            for child, child_pos in zip(direct, head_positions):
-                positions[child.id] = np.array(child_pos)
-
-                # Grandchildren (methods) orbit their parent class
-                grand_ids = children.get(child.id, [])
-                grand = [node_by_id[gid] for gid in grand_ids if gid in node_by_id]
-                n_grand = len(grand)
-                if not grand:
-                    continue
-
-                method_r = self.method_orbit_radius + np.sqrt(n_grand) * 0.15
-                method_positions = fibonacci_sphere(
-                    n_grand, radius=method_r, center=np.array(child_pos)
-                )
-                for gc, gc_pos in zip(grand, method_positions):
-                    positions[gc.id] = np.array(gc_pos)
-
-        # Orphan nodes: anything not yet placed (symbols, unrooted nodes)
-        orphans = [n for n in nodes if n.id not in positions]
-        if orphans:
-            orphan_r = 3.0
-            orphan_positions = fibonacci_sphere(
-                len(orphans), radius=orphan_r, center=np.array([0.0, 0.0, orphan_r])
-            )
-            for n, pos in zip(orphans, orphan_positions):
-                positions[n.id] = np.array(pos)
-
-        return positions
-
-
-# ---------------------------------------------------------------------------
-# FunnelLayout
-# ---------------------------------------------------------------------------
-
-# Z levels and per-level radii come from pycode_kg.theme so the layout engine,
-# the 3-D viewer and the 2-D explorer share one definition.
-_KIND_ZLEVEL: dict[str, int] = dict(theme.KIND_ZLEVEL)
-_LEVEL_NODE_SIZE: dict[int, float] = dict(theme.LEVEL_NODE_SIZE)
-
-
-class FunnelLayout(Layout3D):
-    """
-    Stratified layout: node *kind* determines the Z layer; XY positions use a
-    golden-angle disc spiral within each layer.
-
-    Layers (bottom to top):
-
-    - **Z = 0** — modules
-    - **Z = layer_gap** — classes
-    - **Z = 2 × layer_gap** — functions and methods
-    - **Z = 3 × layer_gap** — symbol stubs
-
-    Cross-cutting edges (``CALLS``, ``IMPORTS``, ``INHERITS``) arc between
-    layers, making structural coupling immediately visible from any angle.
-
-    Disc radius is derived algorithmically:
-    ``r = node_spacing * node_size * sqrt(n)``
-    so the layout scales correctly for repos of any size without hand-tuning.
-
-    :param layer_gap: Vertical distance between adjacent layers.
-    :param node_spacing: Spacing multiplier — larger spreads layers out more.
-    """
-
-    def __init__(
-        self,
-        layer_gap: float = 12.0,
-        node_spacing: float = 2.0,
-    ) -> None:
-        """Initialise layout parameters.
-
-        :param layer_gap: Vertical separation between layers.
-        :param node_spacing: Controls minimum gap between node surfaces.
-        """
-        self.layer_gap = layer_gap
-        self.node_spacing = node_spacing
-
-    def compute(
-        self,
-        nodes: list[LayoutNode],
-        edges: list[LayoutEdge],
-    ) -> dict[str, np.ndarray]:
-        """
-        Compute funnel 3-D positions for all nodes.
-
-        :param nodes: All nodes in the graph.
-        :param edges: Unused by this layout (present for API compatibility).
-        :return: Mapping from node ID to ``[x, y, z]`` position.
-        """
-        # Group nodes by Z layer
-        layers: dict[int, list[LayoutNode]] = {}
-        for n in nodes:
-            level = _KIND_ZLEVEL.get(n.kind, 3)
-            layers.setdefault(level, []).append(n)
-
-        positions: dict[str, np.ndarray] = {}
-
-        for level, layer_nodes in layers.items():
-            z = level * self.layer_gap
-            node_size = _LEVEL_NODE_SIZE.get(level, 0.7)
-            # Derived radius: scales with sqrt(n) and node size so no manual
-            # tuning is needed as the repo grows
-            r = self.node_spacing * node_size * np.sqrt(len(layer_nodes))
-            r = max(r, 4.0)
-            pts = _golden_spiral_2d(len(layer_nodes), radius=r, z=z)
-            for n, pt in zip(layer_nodes, pts):
-                positions[n.id] = pt
-
-        return positions