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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.23.0
+Version: 0.24.0
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -21,8 +21,8 @@ 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: kgmodule-utils[semantic,viz3d] (>=0.12.1)
-Requires-Dist: kgmodule-utils[viz3d-render] (>=0.12.1) ; extra == "viz3d"
+Requires-Dist: kgmodule-utils[semantic,viz3d] (>=0.18.0)
+Requires-Dist: kgmodule-utils[viz3d-qt,viz3d-render] (>=0.18.0) ; extra == "viz3d"
 Requires-Dist: markdown (>=3.6) ; extra == "all"
 Requires-Dist: markdown (>=3.6) ; extra == "viz3d"
 Requires-Dist: mcp (>=1.0.0,<2)
@@ -38,8 +38,8 @@ Requires-Dist: pyvis (>=0.3.2) ; extra == "viz"
 Requires-Dist: pyvista (>=0.44.0) ; extra == "all"
 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: quiltwright (>=0.8.0) ; extra == "all"
+Requires-Dist: quiltwright (>=0.8.0) ; extra == "viz3d"
 Requires-Dist: rich (>=14.3.3,<15)
 Requires-Dist: sentence-transformers (>=5.4.1)
 Requires-Dist: sqlite-vec (==0.1.9)
@@ -60,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.23.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.24.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)
@@ -255,7 +255,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.23.0.md](docs/analysis_v0.23.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.24.0.md](docs/analysis_v0.24.0.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -282,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.23.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.24.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.23.0},
+  version   = {0.24.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.23.0 → pycode_kg-0.24.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.23.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.24.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)
@@ -200,7 +200,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.23.0.md](docs/analysis_v0.23.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.24.0.md](docs/analysis_v0.24.0.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -227,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.23.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.24.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.23.0},
+  version   = {0.24.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

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

@@ -1,7 +1,6 @@
 # pyproject.toml — PyCodeKG package configuration (PEP 621)
 #
 # Author: Eric G. Suchanek, PhD
-# Last Revision: 2026-08-15
 #
 # Build system : Poetry 2.x with PEP 621 [project] table
 #
@@ -71,7 +70,7 @@ torch = [
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.23.0"
+version = "0.24.0"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"
@@ -137,7 +136,21 @@ 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.12.1",
+    # Floor is 0.13.x rather than 0.12.1 because that is where SnapshotManager
+    # stops writing absolute paths into snapshot JSON. This package ships
+    # `pycodekg snapshot save`, and those snapshots get committed to the
+    # user's repo — against an older kgmodule-utils the command writes their
+    # home directory and username into version control.
+    #
+    # 0.13.2 specifically, never 0.13.1: that release carried the path fix but
+    # also made `repo_root` a read-only property, which breaks every subclass
+    # that assigns it. 0.13.2 keeps the fix and restores the plain attribute.
+    #
+    # 0.15.0 because the `viz3d` extra below needs kg_utils.viz3d.qt, and this
+    # repo's own rule is one floor per package — a lower floor here would leave
+    # a reader working out which constraint actually binds. Nothing in the core
+    # install needs 0.15.0 functionally; it is a superset of 0.14.0.
+    "kgmodule-utils[semantic,viz3d]>=0.18.0",
 ]
 
 [project.optional-dependencies]
@@ -154,12 +167,22 @@ viz3d = [
     # 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",
+    # Same floor as the core declaration above — one package, one floor, so a
+    # reader does not have to work out which constraint actually binds.
+    # [viz3d-qt] (new in 0.15.0) adds kg_utils.viz3d.qt — the Qt machinery a
+    # viewer needs to cast: the render lifecycle and cast_scene_to_looking_glass,
+    # which this module's "Cast to LG" button now drives instead of open-coding
+    # the four-step build/render/write/cast itself. It subsumes [viz3d-render]
+    # (it declares pyvista too), but both are named so the dependency reads as
+    # what it is rather than as a side effect.
+    "kgmodule-utils[viz3d-render,viz3d-qt]>=0.18.0",
     "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",
+    # requires-python to <3.14, which retires the old marker gate. 0.6.0 adds
+    # QuiltSpec.scaled(), which replaces the tile-grid rounding this repo used
+    # to open-code, and save_and_cast_quilt() underneath the SDK cast helper.
+    "quiltwright>=0.8.0",
 ]
 
 # Cross-KG sibling packages (doc-kg, pycode-kg, agent-kg, kg-rag) are NOT
@@ -184,7 +207,7 @@ all = [
     "pyvis>=0.3.2",
     "pyvista>=0.44.0",
     "pyvistaqt>=0.11.0",
-    "quiltwright>=0.4.0",
+    "quiltwright>=0.8.0",
     "streamlit>=1.56.0",
     "trame-vtk>=2.0.0",
 ]
@@ -226,7 +249,7 @@ ty = ">=0.0.41"
 optional = true
 
 [tool.poetry.group.kg.dependencies]
-doc-kg = ">=0.21.2"
+doc-kg = ">=0.22.0"
 
 [project.urls]
 Homepage = "https://github.com/Flux-Frontiers/pycode_kg"

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

@@ -36,7 +36,7 @@ Author: Eric G. Suchanek, PhD
 License: Elastic 2.0
 """
 
-__version__ = "0.23.0"
+__version__ = "0.24.0"
 __author__ = "Eric G. Suchanek, PhD"
 
 # Low-level primitives (locked v0 contract)

{pycode_kg-0.23.0 → pycode_kg-0.24.0}/src/pycode_kg/analysis/bridge.py

@@ -4,7 +4,6 @@ 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-14 20:59:39
 License: Elastic 2.0
 """
 

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

@@ -12,7 +12,6 @@ Public API:
     - :func:`aggregate_module_scores` — roll node scores up to module level.
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-08-14 22:45:27
 
 License: Elastic 2.0
 """

{pycode_kg-0.23.0 → pycode_kg-0.24.0}/src/pycode_kg/analysis/framework_detector.py

@@ -3,7 +3,6 @@ Framework Detector for PyCodeKG.
 Identifies repo-defining abstractions using centrality and cross-module signals.
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-08-14 20:59:39
 License: Elastic 2.0
 """
 

{pycode_kg-0.23.0 → pycode_kg-0.24.0}/src/pycode_kg/cli/cmd_hooks.py

@@ -6,7 +6,6 @@ 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-08-11 19:32:52
 
 Author: Eric G. Suchanek, PhD
 
@@ -29,10 +28,33 @@ from pycode_kg.cli.main import cli
 
 _PRE_COMMIT_HOOK = """\
 #!/usr/bin/env bash
-# PyCodeKG pre-commit hook — runs quality checks first, then rebuilds the local
-# index and captures a metrics snapshot.
+# PyCodeKG pre-commit hook — runs quality checks. The index rebuild and metrics
+# snapshot are opt-in and OFF by default; see "Why snapshots are off" below.
 # Installed by: pycodekg install-hooks
-# Skip with: PYCODEKG_SKIP_SNAPSHOT=1 git commit ...
+#
+#   PYCODEKG_SNAPSHOT=1 git commit ...        opt in to a per-commit snapshot
+#   PYCODEKG_SKIP_SNAPSHOT=1 git commit ...   force snapshots off (wins)
+#
+# Note that PYCODEKG_SKIP_SNAPSHOT no longer skips the quality checks. It used
+# to short-circuit the whole hook, so a variable named "skip snapshot" also
+# silently skipped ruff, ty and pytest. It now gates only what it names.
+#
+# Why snapshots are off by default (2026-08-18)
+# ---------------------------------------------
+# A per-commit snapshot records `git write-tree` and is then itself staged into
+# that same commit. Staging changes the index, so the recorded hash can never
+# equal the tree it claims to describe — and manifest.json carries a
+# `last_update` timestamp, so the `git add` is never a no-op. The drift is
+# guaranteed by construction, not caused by formatting, and reordering does not
+# fix it: the `git add` lands after the hash either way.
+#
+# An audit of 605 snapshots across 29 fleet manifests found 63 (10.4%) keyed to
+# a tree any commit actually has. `snapshot diff` between adjacent entries has
+# therefore been comparing states that never existed.
+#
+# The fix is to snapshot at release, keyed on the tag rather than on an
+# ephemeral pre-commit tree. See kgrag_priv/docs/SNAPSHOT_STRATEGY.md. Until
+# that lands, this hook runs quality checks only.
 #
 # Order matters, and it is deliberately checks-then-index:
 #
@@ -46,8 +68,6 @@ _PRE_COMMIT_HOOK = """\
 #     commit that ruff/ty/pytest is about to reject.
 set -euo pipefail
 
-[ "${PYCODEKG_SKIP_SNAPSHOT:-0}" = "1" ] && exit 0
-
 REPO_ROOT="$(git rev-parse --show-toplevel)"
 
 cd "$REPO_ROOT"
@@ -63,12 +83,27 @@ elif command -v pre-commit &>/dev/null; then
     pre-commit run || exit 1
 fi
 
-# Capture the tree hash now that the checks have passed and nothing further
-# will modify the working tree — this keys the snapshot to the content that is
-# actually about to be committed.
+# ---------------------------------------------------------------------------
+# Opt-in index rebuild + snapshot. Everything below is skipped unless
+# PYCODEKG_SNAPSHOT=1 is set, and is skipped regardless if
+# PYCODEKG_SKIP_SNAPSHOT=1.
+# ---------------------------------------------------------------------------
+[ "${PYCODEKG_SNAPSHOT:-0}" = "1" ] || exit 0
+[ "${PYCODEKG_SKIP_SNAPSHOT:-0}" = "1" ] && exit 0
+
+# Captured after the checks so nothing further modifies the working tree. Note
+# the caveat above: this still cannot match the committed tree, because the
+# `git add` below changes the index after this point.
 TREE_HASH=$(git write-tree)
 BRANCH=$(git rev-parse --abbrev-ref HEAD)
 
+# Snapshots are default-branch history. On any other branch, stop here —
+# feature-branch commits (and the PRs/CI built from them) stay free of
+# generated snapshot files, and skip the 60-90s rebuild along the way.
+DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || true)
+DEFAULT_BRANCH="${DEFAULT_BRANCH#origin/}"
+[ "$BRANCH" != "${DEFAULT_BRANCH:-main}" ] && exit 0
+
 # Rebuild the local index to keep it in sync with staged content.
 "$REPO_ROOT/.venv/bin/pycodekg" build --repo "$REPO_ROOT" || exit 1
 
@@ -104,11 +139,14 @@ exit 0
 def install_hooks(repo: str, force: bool) -> None:
     """Install the PyCodeKG pre-commit git hook.
 
-    After installation, before each commit:
+    After installation, before each commit on the default branch:
       1. Rebuilds the local PyCodeKG index (full wipe)
       2. Captures a metrics snapshot, keyed by tree hash
       3. Stages the snapshot directory
 
+    On any other branch the quality checks still run but the rebuild and
+    snapshot are skipped, so feature-branch commits carry no generated files.
+
     This keeps the index in sync and ensures snapshots reflect the state of
     the knowledge graph at commit time.  The hook only ever touches its own
     repository — sibling KG repos install their own hooks.
@@ -137,5 +175,8 @@ def install_hooks(repo: str, force: bool) -> None:
     hook_path.chmod(mode)
 
     click.echo(f"OK Installed pre-commit hook: {hook_path}")
-    click.echo("  Snapshots will be captured automatically before each commit.")
+    click.echo("  Quality checks run on every commit.")
+    click.echo("  Snapshots are OFF by default - see kgrag_priv/docs/SNAPSHOT_STRATEGY.md.")
+    click.echo("  Opt in with:  PYCODEKG_SNAPSHOT=1 git commit ...")
+    click.echo("  Force off:    PYCODEKG_SKIP_SNAPSHOT=1 git commit ...")
     click.echo("  Run 'pycodekg build' first if you haven't built the graph yet.")

{pycode_kg-0.23.0 → pycode_kg-0.24.0}/src/pycode_kg/cli/cmd_init.py

@@ -253,6 +253,8 @@ def init(
 
                 docstring_cov = analysis.get("docstring_coverage", {})
                 coverage = docstring_cov.get("coverage_pct", 0.0) / 100.0 if docstring_cov else 0.0
+                coverage_documented = docstring_cov.get("with_doc", 0)
+                coverage_total = docstring_cov.get("total", 0)
                 critical_issues = len(analysis.get("issues", []))
 
                 fn_metrics = analysis.get("function_metrics", {})
@@ -276,6 +278,8 @@ def init(
                 branch=branch,
                 graph_stats_dict=stats,
                 coverage=coverage,
+                coverage_documented=coverage_documented,
+                coverage_total=coverage_total,
                 critical_issues=critical_issues,
                 complexity_median=complexity_median,
                 hotspots=hotspots,

{pycode_kg-0.23.0 → pycode_kg-0.24.0}/src/pycode_kg/cli/cmd_quilt.py

@@ -12,7 +12,6 @@ in :mod:`quiltwright`.  What this command owns is the part quiltwright cannot
 know: which graph to grow and how to frame it.
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-08-14
 
 License: Elastic 2.0
 """

{pycode_kg-0.23.0 → pycode_kg-0.24.0}/src/pycode_kg/cli/cmd_snapshot.py

@@ -111,6 +111,8 @@ def save_snapshot(
         # Extract metrics from analysis results
         docstring_cov = analysis.get("docstring_coverage", {})
         coverage = docstring_cov.get("coverage_pct", 0.0) / 100.0 if docstring_cov else 0.0
+        coverage_documented = docstring_cov.get("with_doc", 0)
+        coverage_total = docstring_cov.get("total", 0)
         issue_strings = analysis.get("issues", [])
         critical_issues = len(issue_strings)
 
@@ -140,6 +142,8 @@ def save_snapshot(
         branch=branch,
         graph_stats_dict=stats,
         coverage=coverage,
+        coverage_documented=coverage_documented,
+        coverage_total=coverage_total,
         critical_issues=critical_issues,
         complexity_median=complexity_median,
         hotspots=hotspots,

{pycode_kg-0.23.0 → pycode_kg-0.24.0}/src/pycode_kg/pycodekg.py

@@ -23,7 +23,6 @@ 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-08-14 22:45:27
 
 License: Elastic 2.0
 """