pycode-kg 0.27.1__tar.gz → 0.28.1__tar.gz

{pycode_kg-0.27.1 → pycode_kg-0.28.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.27.1
+Version: 0.28.1
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -21,11 +21,11 @@ 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.22.0)
-Requires-Dist: kgmodule-utils[viz3d-qt,viz3d-render] (>=0.22.0) ; extra == "viz3d"
+Requires-Dist: kgmodule-utils[semantic,viz3d] (>=0.23.0)
+Requires-Dist: kgmodule-utils[viz3d-qt,viz3d-render] (>=0.23.0) ; extra == "viz3d"
 Requires-Dist: markdown (>=3.6) ; extra == "all"
 Requires-Dist: markdown (>=3.6) ; extra == "viz3d"
-Requires-Dist: mcp (>=1.0.0,<2)
+Requires-Dist: mcp (>=1.3.0,<2)
 Requires-Dist: networkx (>=3.0)
 Requires-Dist: numpy (>=1.24.0)
 Requires-Dist: pandas (>=2.0.0)
@@ -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.14.1) ; extra == "all"
-Requires-Dist: quiltwright (>=0.14.1) ; extra == "viz3d"
+Requires-Dist: quiltwright (>=0.15.0) ; extra == "all"
+Requires-Dist: quiltwright (>=0.15.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,10 +60,10 @@ 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.27.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.28.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)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19737993-blue.svg)](https://doi.org/10.5281/zenodo.19737993)
 
 # PyCodeKG — A Knowledge Graph for Python Codebases
 
@@ -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.27.1.md](docs/analysis_v0.27.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.28.1.md](docs/analysis_v0.28.1.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -280,15 +280,15 @@ The MCP server, the CLI, and the Streamlit app are thin wrappers over the same s
 
 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)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19737993-blue.svg)](https://doi.org/10.5281/zenodo.19737993)
 
-> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.27.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.28.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.27.1},
+  version   = {0.28.1},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.27.1 → pycode_kg-0.28.1}/README.md

@@ -5,10 +5,10 @@
 
 [![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.27.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.28.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)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19737993-blue.svg)](https://doi.org/10.5281/zenodo.19737993)
 
 # PyCodeKG — A Knowledge Graph for Python Codebases
 
@@ -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.27.1.md](docs/analysis_v0.27.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.28.1.md](docs/analysis_v0.28.1.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -225,15 +225,15 @@ The MCP server, the CLI, and the Streamlit app are thin wrappers over the same s
 
 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)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19737993-blue.svg)](https://doi.org/10.5281/zenodo.19737993)
 
-> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.27.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.28.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.27.1},
+  version   = {0.28.1},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.27.1 → pycode_kg-0.28.1}/pyproject.toml

@@ -70,7 +70,7 @@ torch = [
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.27.1"
+version = "0.28.1"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"
@@ -96,7 +96,7 @@ dependencies = [
     # FastMCP from mcp, so an unbounded floor lets a clean install pull 2.x and
     # break `pycodekg-mcp` at import time. Lift this only alongside a port to
     # the standalone fastmcp package.
-    "mcp>=1.0.0,<2",
+    "mcp>=1.3.0,<2",
     "networkx>=3.0",
     "numpy>=1.24.0",
     "pandas>=2.0.0",
@@ -169,7 +169,7 @@ dependencies = [
     # and the _domain_metrics() hook, none of which exist before 0.20.0.
     # Against 0.19.x the manager silently reports itself as "kg-utils" and
     # drops module_node_counts entirely.
-    "kgmodule-utils[semantic,viz3d]>=0.22.0",
+    "kgmodule-utils[semantic,viz3d]>=0.23.0",
 ]
 
 [project.optional-dependencies]
@@ -194,7 +194,7 @@ viz3d = [
     # 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.22.0",
+    "kgmodule-utils[viz3d-render,viz3d-qt]>=0.23.0",
     "pyvistaqt>=0.11.0",
     "trame-vtk>=2.0.0",
     # Looking Glass quilts. 0.4.0 supplies depth_report() and widened
@@ -204,7 +204,7 @@ viz3d = [
     # 0.14.1 is what kgmodule-utils[viz3d-qt] >=0.22.0 needs transitively, for
     # resolve_view_cone; declared here so this file states the real floor
     # rather than leaving it to the resolver to discover.
-    "quiltwright>=0.14.1",
+    "quiltwright>=0.15.0",
 ]
 
 # Cross-KG sibling packages (doc-kg, pycode-kg, agent-kg, kg-rag) are NOT
@@ -229,7 +229,7 @@ all = [
     "pyvis>=0.3.2",
     "pyvista>=0.44.0",
     "pyvistaqt>=0.11.0",
-    "quiltwright>=0.14.1",
+    "quiltwright>=0.15.0",
     "streamlit>=1.56.0",
     "trame-vtk>=2.0.0",
 ]
@@ -249,30 +249,9 @@ pdoc = ">=14.0.0"
 pre-commit = ">=4.5.1"
 pytest = ">=9.0.3"
 pytest-cov = ">=5.0.0"
-ruff = ">=0.4.0,<0.16"
+ruff = ">=0.15,<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
-# 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.22.0"
-
 [project.urls]
 Homepage = "https://github.com/Flux-Frontiers/pycode_kg"
 Repository = "https://github.com/Flux-Frontiers/pycode_kg"

{pycode_kg-0.27.1 → pycode_kg-0.28.1}/src/pycode_kg/__init__.py

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

{pycode_kg-0.27.1 → pycode_kg-0.28.1}/src/pycode_kg/cli/cmd_hooks.py

@@ -105,10 +105,17 @@ 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
+# pycodekg is a tool this repo runs, not a dependency it declares: the fleet
+# installs it once, globally (uv tool install pycode-kg), so PATH is the normal
+# case. A .venv copy is honoured if present, for a checkout that still has one.
+PYCODEKG="$(command -v pycodekg 2>/dev/null || true)"
+[ -n "$PYCODEKG" ] || PYCODEKG="$REPO_ROOT/.venv/bin/pycodekg"
+[ -x "$PYCODEKG" ] || { echo "[pycodekg] not found on PATH or in .venv; uv tool install pycode-kg" >&2; exit 1; }
+
+"$PYCODEKG" build --repo "$REPO_ROOT" || exit 1
 
 # Snapshot PyCodeKG (version auto-detected from installed package).
-"$REPO_ROOT/.venv/bin/pycodekg" snapshot save \\
+"$PYCODEKG" snapshot save \\
     --repo . \\
     --tree-hash "$TREE_HASH" \\
     --branch "$BRANCH" \\

{pycode_kg-0.27.1 → pycode_kg-0.28.1}/src/pycode_kg/mcp_server.py

@@ -142,6 +142,8 @@ from __future__ import annotations
 import argparse
 import json
 import sys
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from pathlib import Path
 
 from mcp.server.fastmcp import FastMCP
@@ -266,6 +268,22 @@ def _snapshot_freshness(snapshot_total_nodes: int) -> dict:
 # MCP server
 # ---------------------------------------------------------------------------
 
+
+@asynccontextmanager
+async def _lifespan(_server: FastMCP) -> AsyncIterator[None]:
+    """Close the graph's SQLite connection(s) when the server shuts down.
+
+    ``main()`` sets the module-level ``_kg`` before ``mcp.run()`` calls into
+    this, and both the stdio and SSE transports route through the same
+    underlying ``Server.run()``, so this fires on either one.
+    """
+    try:
+        yield
+    finally:
+        if _kg is not None:
+            _kg.close()
+
+
 mcp = FastMCP(
     "pycodekg",
     instructions=(
@@ -396,6 +414,7 @@ mcp = FastMCP(
         "- **Structure-aware query**: query_ranked(q='database connection', mode='hybrid')\n"
         "- **PPR query**: query_ranked(q='...', mode='ppr') → explain_rank(node_id, q='...')"
     ),
+    lifespan=_lifespan,
 )
 
 

{pycode_kg-0.27.1 → pycode_kg-0.28.1}/src/pycode_kg/pycodekg_thorough_analysis.py

@@ -43,6 +43,7 @@ from collections.abc import Callable
 from dataclasses import asdict, dataclass
 from pathlib import Path
 
+from kg_utils.vector_backend import VectorStoreNotFoundError
 from rich.columns import Columns
 from rich.console import Console
 from rich.panel import Panel
@@ -444,6 +445,8 @@ class PyCodeKGAnalyzer:
         self.concern_analysis: list[dict] = []  # populated by _analyze_concerns
         # Single-line phase output: each phase fn writes its summary here
         self._phase_result: str = ""
+        # Phases that raised; rendered in the report (see _run_phase)
+        self.phase_failures: list[dict] = []
 
     # ── total phase count (update if phases are added/removed) ────────────────
     _TOTAL_PHASES = 15
@@ -455,13 +458,39 @@ class PyCodeKGAnalyzer:
         instead of printing directly, keeping the terminal output to one line
         per phase.
 
+        A phase that cannot run must not take the others and the report with
+        it. The concrete case is ``pycodekg build-sqlite``, a supported command
+        that builds the graph without the vector index: the fan-out and
+        concern-ranking phases seed on a semantic query and raise
+        ``VectorStoreNotFoundError``, while every other phase reads the graph
+        only. The failure is recorded in :attr:`phase_failures` and rendered in
+        the report, so a degraded run names its missing sections instead of
+        quietly omitting them.
+
         :param num: Phase number (1-based).
         :param name: Human-readable phase label.
         :param fn: Zero-argument callable to execute.
         """
         self._phase_result = ""
         t0 = time.monotonic()
-        fn()
+        try:
+            fn()
+        except Exception as exc:  # noqa: BLE001 -- see docstring
+            elapsed = time.monotonic() - t0
+            self.phase_failures.append(
+                {
+                    "phase": num,
+                    "name": name,
+                    "error": str(exc),
+                    "missing_index": isinstance(exc, VectorStoreNotFoundError),
+                }
+            )
+            logger.warning("Phase %d (%s) failed: %s", num, name, exc)
+            self.console.print(
+                f"  [cyan]▶ Phase {num:2d}/{self._TOTAL_PHASES}:[/cyan]"
+                f" {name}  [yellow]skipped: {exc}[/yellow]  [green]({elapsed:.1f}s)[/green]"
+            )
+            return
         elapsed = time.monotonic() - t0
         result = f"  {self._phase_result}" if self._phase_result else ""
         self.console.print(
@@ -2505,6 +2534,9 @@ class PyCodeKGAnalyzer:
             "coderank_top_nodes": self.coderank_top_nodes,
             # Option D: concern-based hybrid ranking
             "concern_analysis": self.concern_analysis,
+            # An empty section above may mean a phase did not run, not that
+            # the codebase has nothing to show.
+            "phase_failures": self.phase_failures,
         }
 
     def to_markdown(self, *, metadata: str = "", elapsed_seconds: float | None = None) -> str:

{pycode_kg-0.27.1 → pycode_kg-0.28.1}/src/pycode_kg/report.py

@@ -124,6 +124,35 @@ def render_markdown(analyzer, *, metadata: str = "", elapsed_seconds: float | No
     out += [f"# {repo_name} Analysis", "", f"**Generated:** {generated}"]
     rule()
 
+    # ── Incomplete Analysis ──────────────────────────────────────────────
+    # A phase that could not run leaves its section empty. Said plainly, that
+    # is a missing build step; left unsaid, it reads as a finding about the code.
+    failures = analyzer.phase_failures
+    if failures:
+        out += [
+            "## Incomplete Analysis",
+            "",
+            f"{len(failures)} of {analyzer._TOTAL_PHASES} phases could not run. "
+            "The sections they produce are missing from this report -- that is a "
+            "gap in the analysis, not a finding about the code.",
+            "",
+        ]
+        out += md_table(
+            ["Phase", "Name", "Reason"],
+            [(f["phase"], f["name"], f"`{f['error']}`") for f in failures],
+            aligns="rll",
+        )
+        if any(f["missing_index"] for f in failures):
+            out += [
+                "",
+                "> The semantic index is missing. Only the fan-out and concern-based "
+                "ranking phases need it; every other phase reads the SQLite graph "
+                "directly, which is why the rest of this report is complete. Run "
+                "`pycodekg build-index` (or `pycodekg build`) to build it, then "
+                "re-run the analysis.",
+            ]
+        rule()
+
     # ── Executive Summary ────────────────────────────────────────────────
     out += [
         "## Executive Summary",