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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.28.0
+Version: 0.28.2
 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.23.0)
-Requires-Dist: kgmodule-utils[viz3d-qt,viz3d-render] (>=0.23.0) ; extra == "viz3d"
+Requires-Dist: kgmodule-utils[semantic,viz3d] (>=0.27.0)
+Requires-Dist: kgmodule-utils[viz3d-qt,viz3d-render] (>=0.27.0) ; extra == "viz3d"
 Requires-Dist: markdown (>=3.6) ; extra == "all"
 Requires-Dist: markdown (>=3.6) ; extra == "viz3d"
 Requires-Dist: mcp (>=1.3.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.15.0) ; extra == "all"
-Requires-Dist: quiltwright (>=0.15.0) ; extra == "viz3d"
+Requires-Dist: quiltwright (>=0.16.0) ; extra == "all"
+Requires-Dist: quiltwright (>=0.16.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.28.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.28.2-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.2.md](docs/analysis_v0.28.2.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.2) [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.2},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.28.0 → pycode_kg-0.28.2}/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.2-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.2.md](docs/analysis_v0.28.2.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.2) [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.2},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

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

@@ -70,7 +70,7 @@ torch = [
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.28.0"
+version = "0.28.2"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.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.23.0",
+    "kgmodule-utils[semantic,viz3d]>=0.27.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.23.0",
+    "kgmodule-utils[viz3d-render,viz3d-qt]>=0.27.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.15.0",
+    "quiltwright>=0.16.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.15.0",
+    "quiltwright>=0.16.0",
     "streamlit>=1.56.0",
     "trame-vtk>=2.0.0",
 ]

{pycode_kg-0.28.0 → pycode_kg-0.28.2}/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.2"
 __author__ = "Eric G. Suchanek, PhD"
 
 # Low-level primitives (locked v0 contract)

{pycode_kg-0.28.0 → pycode_kg-0.28.2}/src/pycode_kg/pycodekg_thorough_analysis.py

@@ -27,6 +27,7 @@ Author: Eric G. Suchanek, PhD
 License: Elastic 2.0
 """
 
+import ast
 import datetime
 import importlib
 import inspect
@@ -43,6 +44,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
@@ -135,6 +137,28 @@ _PROPERTY_DECORATOR_RE = re.compile(
     r"@(?:functools\.)?(?:cached_)?property\b|@\w[\w.]*\.(?:setter|getter|deleter)\b"
 )
 
+# Route-registration decorator attributes on a web-framework app or router:
+# ``@app.get(...)``, ``@router.post(...)``, ``@app.middleware("http")``
+# (FastAPI, Starlette) and ``@app.route(...)`` (Flask).  The framework calls
+# the handler, so the graph never sees a CALLS edge to it.
+_ROUTE_DECORATOR_ATTRS = frozenset(
+    {
+        "get",
+        "post",
+        "put",
+        "patch",
+        "delete",
+        "head",
+        "options",
+        "api_route",
+        "route",
+        "middleware",
+        "websocket",
+        "exception_handler",
+        "on_event",
+    }
+)
+
 # Builtin container/str method names live in pycode_kg.resolution, where the
 # post-build hook prunes their bogus RESOLVES_TO edges at the source.  The
 # analyzer still guards its own reads (chain tracing, fan-out) so it stays
@@ -355,6 +379,33 @@ def _has_property_decorator(source_lines: list[str], def_lineno: int) -> bool:
     return False
 
 
+def _has_route_decorator(source: str, def_lineno: int) -> bool:
+    """Check whether the ``def`` at *def_lineno* is registered as a web route.
+
+    Matches a decorator of the form ``@<obj>.<attr>`` or ``@<obj>.<attr>(...)``
+    with ``attr`` in :data:`_ROUTE_DECORATOR_ATTRS`.  The module is parsed
+    rather than scanned line by line because route decorators often span
+    several lines (``@app.post(\n    "/x",\n    response_model=M,\n)``).
+
+    :param source: Full module source text.
+    :param def_lineno: 1-based line number of the ``def`` statement.
+    :return: True when a route-registration decorator precedes the definition;
+        False when it does not, or the source does not parse.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return False
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.lineno == def_lineno:
+            for dec in node.decorator_list:
+                target = dec.func if isinstance(dec, ast.Call) else dec
+                if isinstance(target, ast.Attribute) and target.attr in _ROUTE_DECORATOR_ATTRS:
+                    return True
+            return False
+    return False
+
+
 def _dotted_module(module_path: str) -> str:
     """Convert a repo-relative module path to its dotted import path.
 
@@ -444,6 +495,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 +508,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(
@@ -899,6 +978,8 @@ class PyCodeKGAnalyzer:
         - Property-family methods — accessed as attributes, not calls
         - MCP tools in ``mcp_server.py`` — dispatched by the MCP router
         - Click handlers in CLI modules — dispatched by Click
+        - Web route handlers (``@app.get``, ``@router.post``,
+          ``@app.middleware``, ...) -- dispatched by the web framework
         - ``visit_*`` on ``ast.NodeVisitor`` subclasses — ``getattr`` dispatch
         - Overrides of SDK protocol methods on classes with external bases —
           invoked by the kg_utils pipeline
@@ -985,6 +1066,14 @@ class PyCodeKGAnalyzer:
                 if len(re.findall(rf"\b{re.escape(name)}\b", source)) > 1:
                     return True
 
+        # Web route handlers: registered by decorator and called by the
+        # framework's router, so no CALLS edge reaches them.
+        if kind in ("function", "method"):
+            source = self._module_source(module)
+            lineno = node.get("lineno")
+            if source and lineno and _has_route_decorator(source, lineno):
+                return True
+
         return False
 
     def _is_unverifiable_override(self, node: dict, ctx: dict) -> bool:
@@ -2505,6 +2594,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.2}/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",