pycode-kg 0.24.1__tar.gz → 0.25.1__tar.gz

{pycode_kg-0.24.1 → pycode_kg-0.25.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.24.1
+Version: 0.25.1
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -21,7 +21,7 @@ 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.18.1)
+Requires-Dist: kgmodule-utils[semantic,viz3d] (>=0.19.0)
 Requires-Dist: kgmodule-utils[viz3d-qt,viz3d-render] (>=0.18.1) ; extra == "viz3d"
 Requires-Dist: markdown (>=3.6) ; extra == "all"
 Requires-Dist: markdown (>=3.6) ; extra == "viz3d"
@@ -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.24.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.25.1-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.24.1.md](docs/analysis_v0.24.1.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.25.1.md](docs/analysis_v0.25.1.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.24.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.25.1) [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.24.1},
+  version   = {0.25.1},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},
@@ -312,5 +312,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 August 2026*
+*Built for Python developers and AI agents that work alongside them — egs*
 

{pycode_kg-0.24.1 → pycode_kg-0.25.1}/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.24.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.25.1-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.24.1.md](docs/analysis_v0.24.1.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.25.1.md](docs/analysis_v0.25.1.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.24.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.25.1) [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.24.1},
+  version   = {0.25.1},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},
@@ -257,4 +257,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 August 2026*
+*Built for Python developers and AI agents that work alongside them — egs*

{pycode_kg-0.24.1 → pycode_kg-0.25.1}/pyproject.toml

@@ -70,7 +70,7 @@ torch = [
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.24.1"
+version = "0.25.1"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"
@@ -155,7 +155,7 @@ dependencies = [
     # this repo's visitor writes as of 0.24.1 -- against 0.18.0 the stubs are
     # tagged correctly but the tag is silently ignored, so resolution stays on
     # the old untyped trailing-name match with no error to say so.
-    "kgmodule-utils[semantic,viz3d]>=0.18.1",
+    "kgmodule-utils[semantic,viz3d]>=0.19.0",
 ]
 
 [project.optional-dependencies]

{pycode_kg-0.24.1 → pycode_kg-0.25.1}/src/pycode_kg/__init__.py

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

{pycode_kg-0.24.1 → pycode_kg-0.25.1}/src/pycode_kg/cli/cmd_snapshot.py

@@ -61,7 +61,13 @@ def snapshot() -> None:
     "--tree-hash",
     default="",
     type=str,
-    help="Git tree hash; auto-detected if not provided.",
+    help="Git tree hash, recorded as provenance; auto-detected if not provided.",
+)
+@click.option(
+    "--subject",
+    default="",
+    type=str,
+    help="What was measured, e.g. 'repo:pycode-kg' or 'corpus:pepys'.",
 )
 def save_snapshot(
     version: str | None,
@@ -70,16 +76,25 @@ def save_snapshot(
     snapshots_dir: str | None,
     branch: str | None,
     tree_hash: str,
+    subject: str,
 ) -> None:
     """
     Capture current PyCodeKG metrics and save as a temporal snapshot.
 
     Reads graph statistics, docstring coverage, and complexity metrics from
-    the SQLite graph, then saves a snapshot tagged with the given VERSION.
-    The tree hash is auto-detected from git when not provided.
+    the SQLite graph, then saves a snapshot keyed on VERSION.
+
+    **Pass VERSION explicitly at release time.** An omitted VERSION is
+    auto-detected from the installed pycode-kg package, which names the
+    measuring tool rather than the repo being measured -- in any repo other
+    than this one that is the wrong number, so it is recorded as the version
+    but never used as the key. Omitting it keys the snapshot on a UTC
+    timestamp instead, which is the right answer for a corpus.
 
-    Snapshots are stored in .pycodekg/snapshots/{tree_hash}.json, with a
-    manifest.json tracking all snapshots and their metrics.
+    Snapshots are stored in .pycodekg/snapshots/{key}.json, with a
+    manifest.json tracking all snapshots and their metrics. The git tree hash
+    is recorded as provenance and is no longer the key: it is read before
+    `git add` stages the snapshot, so it names a tree that is never committed.
 
     Example:
         pycodekg snapshot save 0.5.1 --repo .
@@ -149,6 +164,10 @@ def save_snapshot(
         hotspots=hotspots,
         issues=issue_strings,
         tree_hash=tree_hash,
+        # An explicit VERSION is a release tag and becomes the key. An
+        # auto-detected one is the measuring tool's version and must not be.
+        key=version or "",
+        subject=subject or "",
     )
 
     snapshot_file = snap_mgr.save_snapshot(snapshot_obj)

{pycode_kg-0.24.1 → pycode_kg-0.25.1}/src/pycode_kg/snapshots.py

@@ -181,6 +181,12 @@ class Snapshot(_BaseSnapshot):
     The underlying ``metrics``, ``vs_previous``, and ``vs_baseline`` fields
     remain plain dicts on disk; the properties are view-only adapters.
 
+    ``to_dict`` is **not** overridden. The base reads those three fields out of
+    ``__dict__`` rather than through these properties (kgmodule-utils 0.19.0),
+    which is what the override used to exist for -- and the base is also what
+    supplies the current key scheme, so an override here would silently keep
+    writing tree-hash keys.
+
     Implementation note
     -------------------
     Python dataclass fields are stored in ``__dict__`` under their field name.
@@ -225,20 +231,6 @@ class Snapshot(_BaseSnapshot):
         else:
             self.__dict__["vs_baseline"] = value
 
-    def to_dict(self) -> dict[str, Any]:
-        """Convert snapshot to a JSON-serializable dictionary."""
-        return {
-            "key": self.tree_hash,
-            "branch": self.branch,
-            "timestamp": self.timestamp,
-            "version": self.version,
-            "metrics": self.__dict__["metrics"],
-            "hotspots": self.hotspots,
-            "issues": self.issues,
-            "vs_previous": self.__dict__["vs_previous"],
-            "vs_baseline": self.__dict__["vs_baseline"],
-        }
-
     @staticmethod
     def from_dict(data: dict[str, Any]) -> Snapshot:  # type: ignore[override]
         """Reconstruct a pycode-kg ``Snapshot`` from a dictionary."""
@@ -302,6 +294,8 @@ class SnapshotManager(_BaseSnapshotManager):
         hotspots: list[dict[str, Any]] | None = None,
         issues: list[str] | None = None,
         tree_hash: str = "",
+        key: str = "",
+        subject: str = "",
     ) -> Snapshot:
         """Capture a pycode-kg snapshot.
 
@@ -324,7 +318,11 @@ class SnapshotManager(_BaseSnapshotManager):
         :param complexity_median: Median fan-in across functions.
         :param hotspots: Top hotspot entries.
         :param issues: Issue description strings.
-        :param tree_hash: Git tree hash; auto-detected if not provided.
+        :param tree_hash: Git tree hash, recorded as provenance; auto-detected
+            if not provided. It is not the snapshot's key.
+        :param key: Snapshot identifier. Pass the release tag at release time;
+            omit it and the base assigns a UTC timestamp.
+        :param subject: What was measured, e.g. ``repo:pycode-kg``.
         :return: New :class:`Snapshot` instance (not yet persisted).
         """
         module_node_counts = self._collect_module_node_counts()
@@ -334,6 +332,8 @@ class SnapshotManager(_BaseSnapshotManager):
             branch=branch,
             graph_stats_dict=graph_stats_dict,
             tree_hash=tree_hash,
+            key=key,
+            subject=subject,
             hotspots=hotspots,
             issues=issues,
             docstring_coverage=coverage,
@@ -472,6 +472,10 @@ class SnapshotManager(_BaseSnapshotManager):
                 vs_previous=snapshot.__dict__["vs_previous"],
                 vs_baseline=snapshot.__dict__["vs_baseline"],
                 tree_hash=snapshot.tree_hash,
+                snapshot_key=snapshot.snapshot_key,
+                subject=snapshot.subject,
+                tool=snapshot.tool,
+                tool_version=snapshot.tool_version,
             )
             return super().save_snapshot(raw, force=force)
         return super().save_snapshot(snapshot, force=force)