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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.22.0
+Version: 0.23.0
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -16,15 +16,13 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: all
-Provides-Extra: dev
 Provides-Extra: viz
 Provides-Extra: viz3d
 Requires-Dist: PyQt5 (>=5.15.0) ; extra == "all"
 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,viz3d] (>=0.11.0)
+Requires-Dist: kgmodule-utils[semantic,viz3d] (>=0.12.1)
+Requires-Dist: kgmodule-utils[viz3d-render] (>=0.12.1) ; extra == "viz3d"
 Requires-Dist: markdown (>=3.6) ; extra == "all"
 Requires-Dist: markdown (>=3.6) ; extra == "viz3d"
 Requires-Dist: mcp (>=1.0.0,<2)
@@ -33,34 +31,24 @@ Requires-Dist: numpy (>=1.24.0)
 Requires-Dist: pandas (>=2.0.0)
 Requires-Dist: param (>=2.0.0) ; extra == "all"
 Requires-Dist: param (>=2.0.0) ; extra == "viz3d"
-Requires-Dist: pdoc (>=14.0.0) ; extra == "all"
-Requires-Dist: pdoc (>=14.0.0) ; extra == "dev"
 Requires-Dist: plotly (>=5.14.0) ; extra == "all"
 Requires-Dist: plotly (>=5.14.0) ; extra == "viz"
-Requires-Dist: pre-commit (>=4.5.1) ; extra == "all"
-Requires-Dist: pre-commit (>=4.5.1) ; extra == "dev"
-Requires-Dist: pytest (>=8.0.0) ; extra == "all"
-Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
-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 (>=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: quiltwright (>=0.4.0) ; extra == "all"
+Requires-Dist: quiltwright (>=0.4.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: sentence-transformers (>=5.4.1)
 Requires-Dist: sqlite-vec (==0.1.9)
+Requires-Dist: starlette (>=0.49.1,<1.4.0)
 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: ty (>=0.0.41) ; extra == "all"
-Requires-Dist: ty (>=0.0.41) ; extra == "dev"
 Project-URL: Homepage, https://github.com/Flux-Frontiers/pycode_kg
 Project-URL: Repository, https://github.com/Flux-Frontiers/pycode_kg
 Description-Content-Type: text/markdown
@@ -72,7 +60,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.22.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.23.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)
@@ -81,7 +69,7 @@ Description-Content-Type: text/markdown
 
 **PyCodeKG turns a Python codebase into a deterministic, queryable knowledge graph — and uses it to produce architectural analyses you can act on, with or without an LLM in the loop.**
 
-It walks the AST of every module, class, function, and method in your repo, extracts the typed relationships that actually hold the code together (`CONTAINS`, `CALLS`, `IMPORTS`, `INHERITS`, `RESOLVES_TO`), and stores the result in SQLite. A sqlite-vec vector index sits alongside the graph so that *"authentication flow"* and *"verify_jwt"* both find the right place to start exploring. From there you can rank functions by structural importance, trace fan-in across import aliases, detect circular imports and dead code, render the call graph in 3D, snapshot metrics for diffing across releases, or hand the whole thing to Claude over MCP.
+It walks the AST of every module, class, function, and method in your repo, extracts the typed relationships that actually hold the code together (`CONTAINS`, `CALLS`, `IMPORTS`, `INHERITS`, `RESOLVES_TO`), and stores the result in SQLite. A sqlite-vec vector index sits alongside the graph so that *"authentication flow"* and *"verify_jwt"* both find the right place to start exploring. From there you can rank functions by structural importance, trace fan-in across import aliases, detect circular imports and dead code, render the call graph in 3D, grow the repo as a tree you can put on a holographic display, snapshot metrics for diffing across releases, or hand the whole thing to Claude over MCP.
 
 The original motivation was simple: **produce thorough, defensible analyses of Python codebases that don't depend on inference**. Every result is computed from the AST and the graph — no model is asked to guess. When an LLM is present, it consumes the *same* grounded output as a structured context pack, and the hallucinations that plague "embed-the-repo" tools largely disappear.
 
@@ -93,15 +81,11 @@ Everything runs on your laptop. No cloud APIs, no quotas, no source code leaving
 
 ## Sister projects
 
-PyCodeKG is part of a growing family of knowledge-graph systems that share the same hybrid semantic-plus-structural design — each one applies it to a different kind of corpus:
-
-- **[DocKG](https://github.com/Flux-Frontiers/doc_kg)** — Markdown and prose. Indexes PyCodeKG's own documentation, so the docs you're reading are themselves a queryable graph.
-- **[MetaboKG](https://github.com/Flux-Frontiers/metabo_kg)** — metabolic pathway data (KEGG, SBML, BioPAX), with FBA / ODE simulation on top of the graph.
-- **[DiaryKG](https://github.com/Flux-Frontiers/diary_kg)** — personal journals and diary corpora; semantic search and graph traversal over a writer's body of work.
-- **[FTreeKG](https://github.com/Flux-Frontiers/FTreeKG)** — filesystem trees as a queryable graph of directories, files, and contents.
-- **[AgentKG](https://github.com/Flux-Frontiers/agent_kg)** — conversational memory as a knowledge graph: turns, decisions, commitments, preferences, and the relationships between them.
-
-Together they form **KGRAG**, a federated retrieval layer where one query can span code, documentation, journals, filesystems, agent memory, and domain data simultaneously.
+PyCodeKG is one of ten knowledge graphs sharing the same hybrid
+semantic-plus-structural design — code, prose, journals, filesystems, agent
+memory, metabolic pathways — federated by **[KGRAG](https://github.com/Flux-Frontiers/KGRAG)**
+so a single query can span all of them. The full list is in
+[docs/SISTER_PROJECTS.md](docs/SISTER_PROJECTS.md).
 
 ---
 
@@ -184,7 +168,7 @@ pycodekg init --repo .                    # download model, build graph, install
 pycodekg analyze .                        # the architectural report
 ```
 
-That's the recommended path. Variants (minimal install, MCP-only, contributor setup) are in [docs/INSTALLATION.md](docs/INSTALLATION.md). Every CLI subcommand is also exposed as a script alias (`pycodekg-analyze`, `pycodekg-build`, `pycodekg-mcp`, …) for use in Makefiles and Poetry projects.
+That's the recommended path. Variants (minimal install, MCP-only, contributor setup) are in [docs/INSTALLATION.md](docs/INSTALLATION.md). Every capability is a subcommand of the single `pycodekg` entry point — `pycodekg analyze`, `pycodekg build`, `pycodekg mcp` — so that one name is all a Makefile or an MCP config needs.
 
 ---
 
@@ -201,6 +185,33 @@ The graph is built around four node kinds (module, class, function, method) and
 
 ---
 
+## The repo as a tree
+
+`pycodekg viz3d --layout organic` grows the graph instead of plotting it. A
+skeleton is grown toward the code by space colonization, so the shape is the
+data rather than decoration:
+
+- **The trunk** is the repository; its radius follows the pipe model, so it
+  reports how much code the tree carries.
+- **Each limb** is a module. Its *length* is how many definitions the module
+  holds — the biggest module reaches furthest — and its *thickness* follows
+  from the tips it carries.
+- **Each leaf** is a class, function, or method, tinted by kind.
+
+`pycodekg quilt` renders that tree for a [Looking
+Glass](https://lookingglassfactory.com/) light-field display: a multi-view
+quilt the panel fuses into real depth, with `--cast` to send it straight to
+the device. Every render prints its disparity budget first, so you know
+whether the display will fuse the views or ghost them. Details in
+[docs/VIZ3D.md](docs/VIZ3D.md).
+
+The growth engine is shared across the KG fleet
+([kgmodule-utils](https://pypi.org/project/kgmodule-utils/)) and the
+light-field output is [quiltwright](https://pypi.org/project/quiltwright/);
+what lives here is only the mapping from code to wood.
+
+---
+
 ## What you can do with it
 
 | If you want to… | Reach for | Detail |
@@ -214,6 +225,8 @@ The graph is built around four node kinds (module, class, function, method) and
 | **Browse the graph interactively** | `pycodekg viz` (Streamlit) | [docs/INSTALLATION.md](docs/INSTALLATION.md) |
 | **Share a graph as one file** | `pycodekg viz-export -o graph.html` | opens from `file://`, no server |
 | **See call graphs in 3-D** *(active development — functional but rough)* | `pycodekg viz3d --layout funnel` | [docs/VIZ3D.md](docs/VIZ3D.md) |
+| **Grow the repo as a tree** | `pycodekg viz3d --layout organic` | modules are limbs, definitions are leaves |
+| **Render it for a Looking Glass display** | `pycodekg quilt --spec 16-landscape` | [docs/VIZ3D.md](docs/VIZ3D.md) |
 | **Wire it into Claude / Copilot / Cline** | `pycodekg mcp` | [docs/MCP.md](docs/MCP.md) |
 
 If you only read one doc after this one, read [docs/Analyze.md](docs/Analyze.md) — that's where most of the day-to-day value lives.
@@ -229,21 +242,20 @@ src/pycode_kg/
 ├── store.py                         # SQLite persistence + canonical edges
 ├── index.py                         # sqlite-vec semantic index
 ├── pycodekg.py                      # Public façade
-├── pycodekg_query.py                # Hybrid query
-├── pycodekg_snippet_packer.py       # Source-grounded packs
 ├── pycodekg_thorough_analysis.py    # `analyze` engine
 ├── architecture.py                  # `architecture` description generator
 ├── ranking/                         # PageRank, bridge centrality, framework nodes
 ├── snapshots.py                     # Temporal metric snapshots
 ├── analysis/                        # Coupling, cycles, orphans, hotspots
-├── cli/                             # All `pycodekg-*` entry points
+├── cli/                             # `pycodekg` subcommands
 ├── mcp_server.py                    # MCP server (nineteen tools)
 ├── app.py                           # Streamlit web app
 ├── viz3d.py / layout3d.py           # PyVista/PyQt5 3-D viewer
+├── scene3d.py                       # Organic tree: repo → trunk, module → limb
 └── 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.22.0.md](docs/analysis_v0.22.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.23.0.md](docs/analysis_v0.23.0.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -258,7 +270,8 @@ The MCP server, the CLI, and the Streamlit app are thin wrappers over the same s
 | [docs/CODERANK.md](docs/CODERANK.md) | SIR PageRank, bridge centrality, framework hubs |
 | [docs/MCP.md](docs/MCP.md) | MCP server setup for Claude / Kilo / Copilot / Cline, tool reference |
 | [docs/CHEATSHEET.md](docs/CHEATSHEET.md) | Every CLI flag and every MCP tool — one page |
-| [docs/VIZ3D.md](docs/VIZ3D.md) | The 3-D PyVista viewer and layouts |
+| [docs/VIZ3D.md](docs/VIZ3D.md) | The 3-D viewer, the organic tree, and Looking Glass output |
+| [docs/SISTER_PROJECTS.md](docs/SISTER_PROJECTS.md) | The other KGRAG graphs and the shared foundations |
 | [CHANGELOG.md](CHANGELOG.md) | Release history |
 
 ---
@@ -269,13 +282,13 @@ 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.22.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.23.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.22.0},
+  version   = {0.23.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},
@@ -294,7 +307,7 @@ If you use PyCodeKG in your research or project, please cite it:
 ## Support & acknowledgments
 
 - **Issues** — [GitHub Issues](https://github.com/Flux-Frontiers/pycode_kg/issues)
-- Sister projects [DocKG](https://github.com/Flux-Frontiers/doc_kg) and [MetaboKG](https://github.com/Flux-Frontiers/metabo_kg)
+- [Sister projects](docs/SISTER_PROJECTS.md) — the rest of the KGRAG family
 - sqlite-vec, sentence-transformers, PyVista, Streamlit, and FastMCP for the foundations
 
 ---

{pycode_kg-0.22.0 → pycode_kg-0.23.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.22.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.23.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)
@@ -14,7 +14,7 @@
 
 **PyCodeKG turns a Python codebase into a deterministic, queryable knowledge graph — and uses it to produce architectural analyses you can act on, with or without an LLM in the loop.**
 
-It walks the AST of every module, class, function, and method in your repo, extracts the typed relationships that actually hold the code together (`CONTAINS`, `CALLS`, `IMPORTS`, `INHERITS`, `RESOLVES_TO`), and stores the result in SQLite. A sqlite-vec vector index sits alongside the graph so that *"authentication flow"* and *"verify_jwt"* both find the right place to start exploring. From there you can rank functions by structural importance, trace fan-in across import aliases, detect circular imports and dead code, render the call graph in 3D, snapshot metrics for diffing across releases, or hand the whole thing to Claude over MCP.
+It walks the AST of every module, class, function, and method in your repo, extracts the typed relationships that actually hold the code together (`CONTAINS`, `CALLS`, `IMPORTS`, `INHERITS`, `RESOLVES_TO`), and stores the result in SQLite. A sqlite-vec vector index sits alongside the graph so that *"authentication flow"* and *"verify_jwt"* both find the right place to start exploring. From there you can rank functions by structural importance, trace fan-in across import aliases, detect circular imports and dead code, render the call graph in 3D, grow the repo as a tree you can put on a holographic display, snapshot metrics for diffing across releases, or hand the whole thing to Claude over MCP.
 
 The original motivation was simple: **produce thorough, defensible analyses of Python codebases that don't depend on inference**. Every result is computed from the AST and the graph — no model is asked to guess. When an LLM is present, it consumes the *same* grounded output as a structured context pack, and the hallucinations that plague "embed-the-repo" tools largely disappear.
 
@@ -26,15 +26,11 @@ Everything runs on your laptop. No cloud APIs, no quotas, no source code leaving
 
 ## Sister projects
 
-PyCodeKG is part of a growing family of knowledge-graph systems that share the same hybrid semantic-plus-structural design — each one applies it to a different kind of corpus:
-
-- **[DocKG](https://github.com/Flux-Frontiers/doc_kg)** — Markdown and prose. Indexes PyCodeKG's own documentation, so the docs you're reading are themselves a queryable graph.
-- **[MetaboKG](https://github.com/Flux-Frontiers/metabo_kg)** — metabolic pathway data (KEGG, SBML, BioPAX), with FBA / ODE simulation on top of the graph.
-- **[DiaryKG](https://github.com/Flux-Frontiers/diary_kg)** — personal journals and diary corpora; semantic search and graph traversal over a writer's body of work.
-- **[FTreeKG](https://github.com/Flux-Frontiers/FTreeKG)** — filesystem trees as a queryable graph of directories, files, and contents.
-- **[AgentKG](https://github.com/Flux-Frontiers/agent_kg)** — conversational memory as a knowledge graph: turns, decisions, commitments, preferences, and the relationships between them.
-
-Together they form **KGRAG**, a federated retrieval layer where one query can span code, documentation, journals, filesystems, agent memory, and domain data simultaneously.
+PyCodeKG is one of ten knowledge graphs sharing the same hybrid
+semantic-plus-structural design — code, prose, journals, filesystems, agent
+memory, metabolic pathways — federated by **[KGRAG](https://github.com/Flux-Frontiers/KGRAG)**
+so a single query can span all of them. The full list is in
+[docs/SISTER_PROJECTS.md](docs/SISTER_PROJECTS.md).
 
 ---
 
@@ -117,7 +113,7 @@ pycodekg init --repo .                    # download model, build graph, install
 pycodekg analyze .                        # the architectural report
 ```
 
-That's the recommended path. Variants (minimal install, MCP-only, contributor setup) are in [docs/INSTALLATION.md](docs/INSTALLATION.md). Every CLI subcommand is also exposed as a script alias (`pycodekg-analyze`, `pycodekg-build`, `pycodekg-mcp`, …) for use in Makefiles and Poetry projects.
+That's the recommended path. Variants (minimal install, MCP-only, contributor setup) are in [docs/INSTALLATION.md](docs/INSTALLATION.md). Every capability is a subcommand of the single `pycodekg` entry point — `pycodekg analyze`, `pycodekg build`, `pycodekg mcp` — so that one name is all a Makefile or an MCP config needs.
 
 ---
 
@@ -134,6 +130,33 @@ The graph is built around four node kinds (module, class, function, method) and
 
 ---
 
+## The repo as a tree
+
+`pycodekg viz3d --layout organic` grows the graph instead of plotting it. A
+skeleton is grown toward the code by space colonization, so the shape is the
+data rather than decoration:
+
+- **The trunk** is the repository; its radius follows the pipe model, so it
+  reports how much code the tree carries.
+- **Each limb** is a module. Its *length* is how many definitions the module
+  holds — the biggest module reaches furthest — and its *thickness* follows
+  from the tips it carries.
+- **Each leaf** is a class, function, or method, tinted by kind.
+
+`pycodekg quilt` renders that tree for a [Looking
+Glass](https://lookingglassfactory.com/) light-field display: a multi-view
+quilt the panel fuses into real depth, with `--cast` to send it straight to
+the device. Every render prints its disparity budget first, so you know
+whether the display will fuse the views or ghost them. Details in
+[docs/VIZ3D.md](docs/VIZ3D.md).
+
+The growth engine is shared across the KG fleet
+([kgmodule-utils](https://pypi.org/project/kgmodule-utils/)) and the
+light-field output is [quiltwright](https://pypi.org/project/quiltwright/);
+what lives here is only the mapping from code to wood.
+
+---
+
 ## What you can do with it
 
 | If you want to… | Reach for | Detail |
@@ -147,6 +170,8 @@ The graph is built around four node kinds (module, class, function, method) and
 | **Browse the graph interactively** | `pycodekg viz` (Streamlit) | [docs/INSTALLATION.md](docs/INSTALLATION.md) |
 | **Share a graph as one file** | `pycodekg viz-export -o graph.html` | opens from `file://`, no server |
 | **See call graphs in 3-D** *(active development — functional but rough)* | `pycodekg viz3d --layout funnel` | [docs/VIZ3D.md](docs/VIZ3D.md) |
+| **Grow the repo as a tree** | `pycodekg viz3d --layout organic` | modules are limbs, definitions are leaves |
+| **Render it for a Looking Glass display** | `pycodekg quilt --spec 16-landscape` | [docs/VIZ3D.md](docs/VIZ3D.md) |
 | **Wire it into Claude / Copilot / Cline** | `pycodekg mcp` | [docs/MCP.md](docs/MCP.md) |
 
 If you only read one doc after this one, read [docs/Analyze.md](docs/Analyze.md) — that's where most of the day-to-day value lives.
@@ -162,21 +187,20 @@ src/pycode_kg/
 ├── store.py                         # SQLite persistence + canonical edges
 ├── index.py                         # sqlite-vec semantic index
 ├── pycodekg.py                      # Public façade
-├── pycodekg_query.py                # Hybrid query
-├── pycodekg_snippet_packer.py       # Source-grounded packs
 ├── pycodekg_thorough_analysis.py    # `analyze` engine
 ├── architecture.py                  # `architecture` description generator
 ├── ranking/                         # PageRank, bridge centrality, framework nodes
 ├── snapshots.py                     # Temporal metric snapshots
 ├── analysis/                        # Coupling, cycles, orphans, hotspots
-├── cli/                             # All `pycodekg-*` entry points
+├── cli/                             # `pycodekg` subcommands
 ├── mcp_server.py                    # MCP server (nineteen tools)
 ├── app.py                           # Streamlit web app
 ├── viz3d.py / layout3d.py           # PyVista/PyQt5 3-D viewer
+├── scene3d.py                       # Organic tree: repo → trunk, module → limb
 └── 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.22.0.md](docs/analysis_v0.22.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.23.0.md](docs/analysis_v0.23.0.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -191,7 +215,8 @@ The MCP server, the CLI, and the Streamlit app are thin wrappers over the same s
 | [docs/CODERANK.md](docs/CODERANK.md) | SIR PageRank, bridge centrality, framework hubs |
 | [docs/MCP.md](docs/MCP.md) | MCP server setup for Claude / Kilo / Copilot / Cline, tool reference |
 | [docs/CHEATSHEET.md](docs/CHEATSHEET.md) | Every CLI flag and every MCP tool — one page |
-| [docs/VIZ3D.md](docs/VIZ3D.md) | The 3-D PyVista viewer and layouts |
+| [docs/VIZ3D.md](docs/VIZ3D.md) | The 3-D viewer, the organic tree, and Looking Glass output |
+| [docs/SISTER_PROJECTS.md](docs/SISTER_PROJECTS.md) | The other KGRAG graphs and the shared foundations |
 | [CHANGELOG.md](CHANGELOG.md) | Release history |
 
 ---
@@ -202,13 +227,13 @@ 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.22.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.23.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.22.0},
+  version   = {0.23.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},
@@ -227,7 +252,7 @@ If you use PyCodeKG in your research or project, please cite it:
 ## Support & acknowledgments
 
 - **Issues** — [GitHub Issues](https://github.com/Flux-Frontiers/pycode_kg/issues)
-- Sister projects [DocKG](https://github.com/Flux-Frontiers/doc_kg) and [MetaboKG](https://github.com/Flux-Frontiers/metabo_kg)
+- [Sister projects](docs/SISTER_PROJECTS.md) — the rest of the KGRAG family
 - sqlite-vec, sentence-transformers, PyVista, Streamlit, and FastMCP for the foundations
 
 ---

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

@@ -1,13 +1,12 @@
 # pyproject.toml — PyCodeKG package configuration (PEP 621)
 #
 # Author: Eric G. Suchanek, PhD
-# Last Revision: 2026-08-11
+# Last Revision: 2026-08-15
 #
 # Build system : Poetry 2.x with PEP 621 [project] table
 #
 # Quick install (pip)
 # -------------------
-#   pip install -e ".[dev]"             core + dev tools (pytest, ruff, ty, etc.)
 #   pip install -e ".[viz]"             core + Streamlit/Plotly/PyVis visualizer
 #   pip install -e ".[viz3d]"           core + PyVista 3D visualizer
 #   pip install -e ".[all]"             everything above
@@ -15,17 +14,19 @@
 #
 # Quick install (poetry)
 # ----------------------
-#   poetry install --all-extras         everything
-#   poetry install --extras "dev"       core + dev tools only
+#   poetry install --with dev --all-extras   everything
+#   poetry install --with dev           core + dev tools (pytest, ruff, ty, etc.)
 #   poetry install --extras "viz"       core + Streamlit/Plotly visualizer only
 #   poetry install --extras "viz3d"     core + 3D visualizer only
 #   poetry install                      core runtime only
 #
+# Dev tooling lives in the Poetry `dev` group, not an extra, so it stays out
+# of published wheel metadata. pip-only setups can't install it — use poetry
+# for development.
+#
 # First-time setup
 # ----------------
-#   python -m venv .venv
-#   source .venv/bin/activate       # Windows: .venv\Scripts\activate
-#   pip install -e ".[dev]"
+#   poetry install --with dev
 #
 # Run tests
 # ---------
@@ -70,7 +71,7 @@ torch = [
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.22.0"
+version = "0.23.0"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"
@@ -102,6 +103,16 @@ dependencies = [
     "pandas>=2.0.0",
     "rich>=14.3.3,<15",
     "sentence-transformers>=5.4.1",
+    # Upper-bounded to keep resolution single-valued across extras: mcp and
+    # sse-starlette float to any 1.x, but streamlit (viz extra) caps starlette
+    # at <1.4.0. Without this ceiling a bare install resolves 1.6.0 while
+    # --extras viz resolves 1.3.1, poetry locks BOTH with no distinguishing
+    # markers, and an install can unpack the two wheels over the same
+    # starlette/ directory — splicing applications.py into a file matching
+    # neither RECORD hash and surfacing as a SyntaxError importing
+    # mcp.server.fastmcp. 1.3.1 is also the only version pycodekg-mcp is
+    # tested against. Floor matches sse-starlette's own requirement.
+    "starlette>=0.49.1,<1.4.0",
     # 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
@@ -126,19 +137,10 @@ dependencies = [
     # 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",
+    "kgmodule-utils[semantic,viz3d]>=0.12.1",
 ]
 
 [project.optional-dependencies]
-dev = [
-    "detect-secrets>=1.5.0",
-    "ty>=0.0.41",
-    "pdoc>=14.0.0",
-    "pre-commit>=4.5.1",
-    "pytest>=8.0.0",
-    "pytest-cov>=5.0.0",
-    "ruff>=0.4.0",
-]
 viz = [
     "plotly>=5.14.0",
     "pyvis>=0.3.2",
@@ -148,9 +150,16 @@ viz3d = [
     "markdown>=3.6",
     "param>=2.0.0",
     "PyQt5>=5.15.0",
-    "pyvista>=0.44.0",
+    # pyvista comes from the SDK, which is what needs it: tree_mesh, leaf_glyphs
+    # and smooth_paths live there. The main dependency above stays on plain
+    # [viz3d] (numpy only) so the nine repos that take pycode-kg do not acquire
+    # VTK for a layout import; rendering stays opt-in, here.
+    "kgmodule-utils[viz3d-render]>=0.12.1",
     "pyvistaqt>=0.11.0",
     "trame-vtk>=2.0.0",
+    # Looking Glass quilts. 0.4.0 supplies depth_report() and widened
+    # requires-python to <3.14, which retires the old marker gate.
+    "quiltwright>=0.4.0",
 ]
 
 # Cross-KG sibling packages (doc-kg, pycode-kg, agent-kg, kg-rag) are NOT
@@ -160,25 +169,44 @@ viz3d = [
 # doc-kg and pycode-kg each depend on the other. Install them by hand:
 #   pip install doc-kg pycode-kg         # both on PyPI
 #   pip install agent-kg kg-rag          # both on PyPI as of 2026-07-29
+# Union of the user-facing extras: keep this the exact sum of `viz` + `viz3d`
+# above, edited in the same commit as either. Two poetry resolver limits force
+# the hand-copy shape: a self-referential "pycode-kg[viz,viz3d]" is rejected
+# ("listed as a dependency of itself"), and repeating kgmodule-utils[viz3d-render]
+# here collides with the viz3d entry ("<empty>" constraint), so bare pyvista
+# stands in for it — pyvista>=0.44.0 is that extra's entire payload.
+# Dev tooling is deliberately absent: it lives in the Poetry dev group below.
 all = [
-    "detect-secrets>=1.5.0",
     "markdown>=3.6",
     "param>=2.0.0",
-    "pdoc>=14.0.0",
     "plotly>=5.14.0",
-    "pre-commit>=4.5.1",
     "PyQt5>=5.15.0",
-    "pytest>=8.0.0",
-    "pytest-cov>=5.0.0",
+    "pyvis>=0.3.2",
     "pyvista>=0.44.0",
     "pyvistaqt>=0.11.0",
-    "pyvis>=0.3.2",
-    "ruff>=0.4.0",
+    "quiltwright>=0.4.0",
     "streamlit>=1.56.0",
     "trame-vtk>=2.0.0",
-    "ty>=0.0.41",
 ]
 
+# Dev tooling. A group rather than an extra so pytest/ruff/ty/pre-commit stay
+# out of the published wheel metadata — `pip install pycode-kg[dev]` was never
+# meant to be a thing consumers do. Optional to preserve the contract that a
+# bare `poetry install` is core runtime only (same shape as `kg` below).
+#
+#   poetry install --with dev
+[tool.poetry.group.dev]
+optional = true
+
+[tool.poetry.group.dev.dependencies]
+detect-secrets = ">=1.5.0"
+pdoc = ">=14.0.0"
+pre-commit = ">=4.5.1"
+pytest = ">=9.0.3"
+pytest-cov = ">=5.0.0"
+ruff = ">=0.4.0,<0.16"
+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
@@ -198,30 +226,19 @@ all = [
 optional = true
 
 [tool.poetry.group.kg.dependencies]
-doc-kg = ">=0.21.1"
+doc-kg = ">=0.21.2"
 
 [project.urls]
 Homepage = "https://github.com/Flux-Frontiers/pycode_kg"
 Repository = "https://github.com/Flux-Frontiers/pycode_kg"
 
 [project.scripts]
-pycodekg                = "pycode_kg.cli.main:cli"
-pycodekg-analyze        = "pycode_kg.cli.cmd_analyze:analyze"
-pycodekg-architecture   = "pycode_kg.cli.cmd_architecture:architecture"
-pycodekg-build          = "pycode_kg.cli.cmd_build_full:build"
-pycodekg-build-index    = "pycode_kg.cli.cmd_build:build_index"
-pycodekg-build-sqlite   = "pycode_kg.cli.cmd_build:build_sqlite"
-pycodekg-centrality     = "pycode_kg.cli.cmd_centrality:cmd_centrality"
-pycodekg-download-model = "pycode_kg.cli.cmd_model:download_model"
-pycodekg-init           = "pycode_kg.cli.cmd_init:init"
-pycodekg-install-hooks  = "pycode_kg.cli.cmd_hooks:install_hooks"
-pycodekg-mcp            = "pycode_kg.mcp_server:main"
-pycodekg-pack           = "pycode_kg.cli.cmd_query:pack"
-pycodekg-query          = "pycode_kg.cli.cmd_query:query"
-pycodekg-update         = "pycode_kg.cli.cmd_build_full:update"
-pycodekg-viz            = "pycode_kg.cli.cmd_viz:viz"
-pycodekg-viz-timeline   = "pycode_kg.cli.cmd_viz:viz_timeline"
-pycodekg-viz3d          = "pycode_kg.cli.cmd_viz:viz3d"
+# The convenience aliases (`pycodekg-analyze`, `pycodekg-build`, ...) went in
+# 0.23.0: nothing invoked them. `pycodekg-mcp` stays -- the documented Claude
+# Desktop and Copilot configs put that path in users' config files, so dropping
+# it would break their MCP server on upgrade.
+pycodekg     = "pycode_kg.cli.main:cli"
+pycodekg-mcp = "pycode_kg.mcp_server:main"
 
 # ---------------------------------------------------------------------------
 # Tool configuration

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

@@ -30,9 +30,13 @@ Low-level primitives (v0 contract, locked)::
 KGModule SDK (build new domain KGs)::
 
     from pycode_kg import KGModule, KGExtractor, PyCodeKGExtractor, NodeSpec, EdgeSpec
+
+Author: Eric G. Suchanek, PhD
+
+License: Elastic 2.0
 """
 
-__version__ = "0.22.0"
+__version__ = "0.23.0"
 __author__ = "Eric G. Suchanek, PhD"
 
 # Low-level primitives (locked v0 contract)

{pycode_kg-0.22.0 → pycode_kg-0.23.0}/src/pycode_kg/__main__.py

@@ -3,6 +3,10 @@
 Dispatcher for python -m pycode_kg <command> [args...]
 
 Routes to Click group-based CLI.
+
+Author: Eric G. Suchanek, PhD
+
+License: Elastic 2.0
 """
 
 from pycode_kg.cli.main import cli

{pycode_kg-0.22.0 → pycode_kg-0.23.0}/src/pycode_kg/analysis/__init__.py

@@ -1,4 +1,9 @@
-"""Analysis primitives for PyCodeKG."""
+"""Analysis primitives for PyCodeKG.
+
+Author: Eric G. Suchanek, PhD
+
+License: Elastic 2.0
+"""
 
 from kg_utils.analysis.scores import MetricRef, ScoreSet, available_metrics, load_scores
 

{pycode_kg-0.22.0 → pycode_kg-0.23.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-08-03 11:37:06
+Last Revision: 2026-08-14 20:59:39
 License: Elastic 2.0
 """
 

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

@@ -12,7 +12,9 @@ Public API:
     - :func:`aggregate_module_scores` — roll node scores up to module level.
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-08-03 11:37:06
+Last Revision: 2026-08-14 22:45:27
+
+License: Elastic 2.0
 """
 
 from __future__ import annotations

{pycode_kg-0.22.0 → pycode_kg-0.23.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-08-03 11:37:06
+Last Revision: 2026-08-14 20:59:39
 License: Elastic 2.0
 """
 

{pycode_kg-0.22.0 → pycode_kg-0.23.0}/src/pycode_kg/app.py

@@ -10,6 +10,10 @@ Interactive knowledge-graph explorer with:
 
 Run with:
     poetry run pycodekg-viz
+
+Author: Eric G. Suchanek, PhD
+
+License: Elastic 2.0
 """
 
 from __future__ import annotations