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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.28.0
+Version: 0.28.1
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -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.28.0-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://img.shields.io/badge/DOI-10.5281%2Fzenodo.19737993-blue.svg)](https://doi.org/10.5281/zenodo.19737993)
@@ -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.28.0.md](docs/analysis_v0.28.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.28.1.md](docs/analysis_v0.28.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://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.28.0) [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.28.0},
+  version   = {0.28.1},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.28.0 → pycode_kg-0.28.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.28.0-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://img.shields.io/badge/DOI-10.5281%2Fzenodo.19737993-blue.svg)](https://doi.org/10.5281/zenodo.19737993)
@@ -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.28.0.md](docs/analysis_v0.28.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.28.1.md](docs/analysis_v0.28.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://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.28.0) [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.28.0},
+  version   = {0.28.1},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

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

@@ -70,7 +70,7 @@ torch = [
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.28.0"
+version = "0.28.1"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"

{pycode_kg-0.28.0 → 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.28.0"
+__version__ = "0.28.1"
 __author__ = "Eric G. Suchanek, PhD"
 
 # Low-level primitives (locked v0 contract)

{pycode_kg-0.28.0 → 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.28.0 → 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",