pycode-kg 0.17.2__tar.gz → 0.18.2__tar.gz

{pycode_kg-0.17.2 → pycode_kg-0.18.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.17.2
+Version: 0.18.2
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -72,22 +72,21 @@ Project-URL: Repository, https://github.com/Flux-Frontiers/pycode_kg
 Description-Content-Type: text/markdown
 
 
+<p align="center">
+  <img src="assets/logos/pycodeKG.PNG" alt="PyCodeKG" width="200"/>
+</p>
+
 [![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.17.2-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.18.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://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
 
-<p align="center">
-  <img src="assets/logo-md-256x256.png" alt="PyCodeKG logo" width="256"/>
-</p>
-
 **PyCodeKG** — A Deterministic Knowledge Graph for Python Codebases
 with Semantic Indexing and Source-Grounded Snippet Packing
 
 *Author: Eric G. Suchanek, PhD*
-
 *Flux-Frontiers, Liberty TWP, OH*
 
 [Technical Paper (PDF)](article/pycode_kg.pdf)
@@ -98,84 +97,57 @@ with Semantic Indexing and Source-Grounded Snippet Packing
 
 PyCodeKG constructs a **deterministic, explainable knowledge graph** from a Python codebase using static analysis. The graph captures structural relationships — definitions, calls, imports, and inheritance — directly from the Python AST, stores them in SQLite, and augments retrieval with vector embeddings via LanceDB.
 
-Structure is treated as **ground truth**; semantic search is strictly an acceleration layer. The result is a searchable, auditable representation of a codebase that supports precise navigation, contextual snippet extraction, and downstream reasoning without hallucination.
-
----
-
-## What Agents Say
-
-*From independent assessments run against PyCodeKG's own codebase. See [assessments/](assessments/) for the full reports.*
-
-> "The workflow compression is real and substantial. Rather than reading files sequentially or running grep searches in the dark, an agent equipped with PyCodeKG can orient itself in seconds."
-> — Claude Sonnet 4.6
+**No inference required.** The CLI is fully useful as a standalone analysis tool — every result is derived from structure, not generated. When used with AI agents, PyCodeKG gives them structurally-grounded answers: precise callers, real call chains, exact line numbers. Hallucination-resistant by design.
 
-> "Replaces hours of manual exploration with a single call. The most valuable tool in the suite."
-> — Claude Opus 4, on `analyze_repo()`
+Structure is treated as **ground truth**; semantic search is strictly an acceleration layer. The result is a searchable, auditable representation of a codebase that supports precise navigation, contextual snippet extraction, and downstream reasoning without hallucination.
 
-> "It let me move from broad orientation to intent-driven discovery and then to structural validation without dropping down into manual grep or repeated file reads."
-> — GPT-5 (via Cline)
+PyCodeKG uses the same architecture as [DocKG](https://github.com/Flux-Frontiers/doc_kg) but targets Python source code rather than document corpora.
 
-> "Traditional file reading and grep-based exploration are slow, linear, and context-poor. PyCodeKG's semantic search, graph navigation, and architectural analysis provide a quantum leap in speed and depth of understanding."
-> — GPT-4.1
+---
 
-> "`pack_snippets()` provided source excerpts around each hit, making the code instantly readable. Context lines and relevance metadata obviated manual file open."
-> — Raptor Mini
+## Features
 
-> "Dramatically more effective than traditional grep/file-reading workflows. Unique value proposition: hybrid search combining natural-language intent with precise structural relationships."
-> — Claude Haiku 4.5
+- **Static analysis pipeline** — Three-pass AST extraction: structure, call graph, data-flow
+- **Deterministic knowledge graph** — SQLite-backed canonical store with provenance-tracked edges
+- **Symbol resolution** — `RESOLVES_TO` edges bridge cross-module call sites via import aliases
+- **Hybrid query model** — Semantic seeding (LanceDB embeddings) + structural expansion (graph traversal)
+- **Source-grounded snippet packing** — Definition and call-site snippets with line numbers
+- **Precise fan-in lookup** — Two-phase reverse traversal resolving cross-module caller chains
+- **Temporal snapshots** — Save and diff graph metrics across commits and versions
+- **MCP server** — Nineteen tools for AI agent integration
+- **Streamlit web app** — Interactive graph browser, hybrid query UI, snippet pack explorer
+- **3-D visualizer** — PyVista/PyQt5 interactive graph explorer with FunnelLayout and timeline view
+- **Zero-config MCP setup** — Single-line installer configures Claude Code, Kilo Code, GitHub Copilot, and Cline
 
 ---
 
-## Quick Start
+## Installation
 
-Run the one-line installer from within the repo you want to index:
+**Requirements:** Python ≥ 3.12, < 3.14
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Flux-Frontiers/pycode_kg/main/scripts/install-skill.sh | bash
-```
-
-This sets up everything end-to-end:
-
-1. Installs SKILL.md reference files for Claude Code, Kilo Code, and other agents
-2. Installs Claude Code slash commands (`/pycodekg`, `/setup-mcp`)
-3. Installs the `pycode-kg` package if not already present
-4. Builds the SQLite knowledge graph and LanceDB semantic index
-5. Writes MCP configuration for Claude Code, Kilo Code, GitHub Copilot, and Cline
+# pip
+pip install pycode-kg
 
-After the script completes, restart your AI agent to activate the MCP server.
+# With Streamlit web visualizer
+pip install 'pycode-kg[viz]'
 
-```bash
-# Preview without making changes
-curl -fsSL .../install-skill.sh | bash -s -- --dry-run
+# With 3-D visualizer (PyVista/PyQt5)
+pip install 'pycode-kg[viz3d]'
 
-# Claude Code and GitHub Copilot only
-curl -fsSL .../install-skill.sh | bash -s -- --providers claude,copilot
+# Poetry
+poetry add pycode-kg
 ```
 
-→ **Full installation options, manual setup, and MCP config:** [docs/INSTALLATION.md](docs/INSTALLATION.md)
-
----
-
-## Features
-
-- **Static analysis pipeline** — Three-pass AST extraction: structure, call graph, data-flow
-- **Deterministic knowledge graph** — SQLite-backed canonical store with provenance
-- **Symbol resolution** — `RESOLVES_TO` edges bridge cross-module call sites via import aliases
-- **Hybrid query model** — Semantic seeding (LanceDB) + structural expansion (graph traversal)
-- **Source-grounded snippet packing** — Definition and call-site snippets with line numbers
-- **Precise fan-in lookup** — Two-phase reverse traversal resolving cross-module caller chains
-- **MCP server** — Ten tools for AI agent integration
-- **Streamlit web app** — Interactive graph browser, hybrid query UI, snippet pack explorer
-- **3D visualizer** — PyVista/PyQt5 interactive graph explorer
-- **Zero-config MCP setup** — Single-line installer configures Claude Code, Kilo Code, GitHub Copilot, and Cline
+> For the one-line skill installer (MCP config, Claude slash commands, git hooks) see [docs/INSTALLATION.md](docs/INSTALLATION.md).
 
 ---
 
-## Usage
+## Quick Start
 
 ```bash
-# Build the knowledge graph
-pycodekg build --repo /path/to/your/repo
+# Index your repo (SQLite + LanceDB in one step)
+pycodekg build --repo /path/to/repo
 
 # Natural-language query
 pycodekg query "authentication flow"
@@ -184,92 +156,63 @@ pycodekg query "authentication flow"
 pycodekg pack "database connection setup" --format md --out context.md
 
 # Full architectural analysis
-pycodekg analyze /path/to/your/repo
-
-# Launch the interactive web app
-pycodekg viz
-
-# Start the MCP server
-pycodekg mcp --repo /path/to/your/repo
+pycodekg analyze /path/to/repo
 ```
 
-### MCP Tools (once the server is running)
-
-```
-graph_stats()                         # node/edge counts by kind
-query_codebase("authentication flow") # hybrid semantic + structural search
-pack_snippets("database layer")        # source-grounded snippets as Markdown
-get_node("fn:store:GraphStore.write") # fetch a single node by ID
-callers("fn:store:GraphStore.write")  # precise fan-in lookup
-explain("fn:store:GraphStore.write")  # natural-language explanation
-analyze_repo()                        # full architectural analysis as Markdown
-snapshot_list()                       # list saved snapshots with deltas
-snapshot_show("latest")               # inspect the latest snapshot
-snapshot_diff("<key_a>", "<key_b>")   # compare two snapshots
-```
+---
 
-### Python API
+## Usage
 
-```python
-from pycode_kg import PyCodeKG
+### Build and query
 
-kg = PyCodeKG(repo_root="/path/to/repo")
-kg.build(wipe=True)
+```bash
+pycodekg build --repo .                              # full build (SQLite + LanceDB)
+pycodekg build --repo . --include-dir src            # index a specific subtree
+pycodekg query "snapshot freshness comparison"       # hybrid semantic + structural search
+pycodekg pack "graph build pipeline" --format md     # snippet pack for LLM context
+```
 
-result = kg.query("database connection setup", k=8, hop=1)
-for node in result.nodes:
-    print(node["id"], node["name"])
+### Analyze codebase health
 
-pack = kg.pack("authentication flow")
-pack.save("context.md")
+```bash
+pycodekg analyze .                                   # full report + JSON snapshot
 ```
 
----
+### Snapshots
 
-## Architecture
+```bash
+pycodekg snapshot save 0.18.0                        # capture current metrics
+pycodekg snapshot list                               # list all snapshots
+pycodekg snapshot diff <key_a> <key_b>               # compare two versions
+```
 
-<p align="center">
-  <img src="assets/codeKG_arch_square-web.jpg" alt="PyCodeKG architecture workflow" width="600"/>
-</p>
+### Visualize
 
-```
-Repository
-  ↓
-AST parsing — Pass 1: structure, Pass 2: calls, Pass 3: data-flow
-  ↓
-SQLite graph — nodes + edges
-  ↓
-Symbol resolution — RESOLVES_TO edges (sym: stubs → fn:/cls: defs)
-  ↓
-Vector indexing — LanceDB
-  ↓
-Hybrid query — semantic + graph
-  ↓
-Ranking + deduplication
-  ↓
-  ├──▶  Streamlit web app
-  └──▶  MCP server tools
+```bash
+pycodekg viz                                         # Streamlit web app
+pycodekg viz3d --layout funnel                       # 3-D PyVista explorer
+pycodekg viz-timeline                                # metric history timeline
 ```
 
-The five design principles:
+> Full flag reference: [docs/INSTALLATION.md](docs/INSTALLATION.md) · Query patterns: [docs/CHEATSHEET.md](docs/CHEATSHEET.md)
 
-1. **Structure is authoritative** — The AST-derived graph is the source of truth.
-2. **Semantics accelerate, never decide** — Embeddings seed and rank retrieval but never invent structure.
-3. **Everything is traceable** — Nodes and edges map to concrete files and line numbers.
-4. **Determinism over heuristics** — Identical input yields identical output.
-5. **Composable artifacts** — SQLite for structure, LanceDB for vectors, Markdown/JSON for consumption.
+---
+
+## What Agents Say
 
-→ **Full architecture documentation:** [docs/Architecture.md](docs/Architecture.md)
+*From independent assessments run against PyCodeKG's own codebase. See [assessments/](assessments/) for full reports.*
 
----
+> "PyCodeKG compresses a multi-step workflow — semantic search, graph expansion, caller tracing, snippet retrieval, and architectural summarization — into a small set of tools that are fast to invoke and easy to chain. In practice, it let me move from broad orientation to intent-driven discovery and then to structural validation without dropping down into manual grep or repeated file reads."
+> — GPT-5 (via Cline)
 
-## Contribution Checklist
+> "What sets it apart from 'search the repo with embeddings' tools is the structural layer… Verdict: 4.5/5 — recommend without reservation for any non-trivial Python codebase."
+> — Claude Opus 4.7
 
-When changing MCP tools in `src/pycode_kg/mcp_server.py` (signature, params, defaults, or behavior), update all three in the same commit:
+> "PyCodeKG is dramatically more effective than traditional grep/file-reading workflows. Unique value: hybrid search combining natural-language intent with precise structural relationships."
+> — Claude Haiku 4.5
 
-- Module docstring `Tools` list at the top of `src/pycode_kg/mcp_server.py`
-- `mcp = FastMCP(..., instructions=(...))` tool descriptions in `src/pycode_kg/mcp_server.py`
-- The runtime tool implementation and `:param:` docstrings
+> "`pack_snippets()` provided source excerpts around each hit, making the code instantly readable. Context lines and relevance metadata obviated manual file open."
+> — Raptor Mini
 
 ---
 
@@ -281,7 +224,7 @@ If you use PyCodeKG in your research or project, please cite it:
 
 **APA**
 
-> Suchanek, E. G. (2026). *PyCodeKG: Semantic Knowledge Graph for Python Codebases* (Version 0.15.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.PLACEHOLDER
+> Suchanek, E. G. (2026). *PyCodeKG: Semantic Knowledge Graph for Python Codebases* (Version 0.18.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19834777
 
 **BibTeX**
 
@@ -289,11 +232,11 @@ If you use PyCodeKG in your research or project, please cite it:
 @software{suchanek_pycode_kg,
   author    = {Suchanek, Eric G.},
   title     = {{PyCodeKG}: Semantic Knowledge Graph for Python Codebases},
-  version   = {0.15.0},
+  version   = {0.18.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},
-  doi       = {10.5281/zenodo.PLACEHOLDER},
+  doi       = {10.5281/zenodo.19834777},
 }
 ```
 
@@ -301,5 +244,5 @@ If you use PyCodeKG in your research or project, please cite it:
 
 ## License
 
-[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license) — see [LICENSE](LICENSE).
+[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license) — free for non-commercial and internal use; commercial redistribution or hosting requires a license from Flux-Frontiers.
 

pycode_kg-0.18.2/README.md

@@ -0,0 +1,174 @@
+
+<p align="center">
+  <img src="assets/logos/pycodeKG.PNG" alt="PyCodeKG" width="200"/>
+</p>
+
+[![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.18.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://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
+
+**PyCodeKG** — A Deterministic Knowledge Graph for Python Codebases
+with Semantic Indexing and Source-Grounded Snippet Packing
+
+*Author: Eric G. Suchanek, PhD*
+*Flux-Frontiers, Liberty TWP, OH*
+
+[Technical Paper (PDF)](article/pycode_kg.pdf)
+
+---
+
+## Overview
+
+PyCodeKG constructs a **deterministic, explainable knowledge graph** from a Python codebase using static analysis. The graph captures structural relationships — definitions, calls, imports, and inheritance — directly from the Python AST, stores them in SQLite, and augments retrieval with vector embeddings via LanceDB.
+
+**No inference required.** The CLI is fully useful as a standalone analysis tool — every result is derived from structure, not generated. When used with AI agents, PyCodeKG gives them structurally-grounded answers: precise callers, real call chains, exact line numbers. Hallucination-resistant by design.
+
+Structure is treated as **ground truth**; semantic search is strictly an acceleration layer. The result is a searchable, auditable representation of a codebase that supports precise navigation, contextual snippet extraction, and downstream reasoning without hallucination.
+
+PyCodeKG uses the same architecture as [DocKG](https://github.com/Flux-Frontiers/doc_kg) but targets Python source code rather than document corpora.
+
+---
+
+## Features
+
+- **Static analysis pipeline** — Three-pass AST extraction: structure, call graph, data-flow
+- **Deterministic knowledge graph** — SQLite-backed canonical store with provenance-tracked edges
+- **Symbol resolution** — `RESOLVES_TO` edges bridge cross-module call sites via import aliases
+- **Hybrid query model** — Semantic seeding (LanceDB embeddings) + structural expansion (graph traversal)
+- **Source-grounded snippet packing** — Definition and call-site snippets with line numbers
+- **Precise fan-in lookup** — Two-phase reverse traversal resolving cross-module caller chains
+- **Temporal snapshots** — Save and diff graph metrics across commits and versions
+- **MCP server** — Nineteen tools for AI agent integration
+- **Streamlit web app** — Interactive graph browser, hybrid query UI, snippet pack explorer
+- **3-D visualizer** — PyVista/PyQt5 interactive graph explorer with FunnelLayout and timeline view
+- **Zero-config MCP setup** — Single-line installer configures Claude Code, Kilo Code, GitHub Copilot, and Cline
+
+---
+
+## Installation
+
+**Requirements:** Python ≥ 3.12, < 3.14
+
+```bash
+# pip
+pip install pycode-kg
+
+# With Streamlit web visualizer
+pip install 'pycode-kg[viz]'
+
+# With 3-D visualizer (PyVista/PyQt5)
+pip install 'pycode-kg[viz3d]'
+
+# Poetry
+poetry add pycode-kg
+```
+
+> For the one-line skill installer (MCP config, Claude slash commands, git hooks) see [docs/INSTALLATION.md](docs/INSTALLATION.md).
+
+---
+
+## Quick Start
+
+```bash
+# Index your repo (SQLite + LanceDB in one step)
+pycodekg build --repo /path/to/repo
+
+# Natural-language query
+pycodekg query "authentication flow"
+
+# Source-grounded snippet pack — paste straight into an LLM prompt
+pycodekg pack "database connection setup" --format md --out context.md
+
+# Full architectural analysis
+pycodekg analyze /path/to/repo
+```
+
+---
+
+## Usage
+
+### Build and query
+
+```bash
+pycodekg build --repo .                              # full build (SQLite + LanceDB)
+pycodekg build --repo . --include-dir src            # index a specific subtree
+pycodekg query "snapshot freshness comparison"       # hybrid semantic + structural search
+pycodekg pack "graph build pipeline" --format md     # snippet pack for LLM context
+```
+
+### Analyze codebase health
+
+```bash
+pycodekg analyze .                                   # full report + JSON snapshot
+```
+
+### Snapshots
+
+```bash
+pycodekg snapshot save 0.18.0                        # capture current metrics
+pycodekg snapshot list                               # list all snapshots
+pycodekg snapshot diff <key_a> <key_b>               # compare two versions
+```
+
+### Visualize
+
+```bash
+pycodekg viz                                         # Streamlit web app
+pycodekg viz3d --layout funnel                       # 3-D PyVista explorer
+pycodekg viz-timeline                                # metric history timeline
+```
+
+> Full flag reference: [docs/INSTALLATION.md](docs/INSTALLATION.md) · Query patterns: [docs/CHEATSHEET.md](docs/CHEATSHEET.md)
+
+---
+
+## What Agents Say
+
+*From independent assessments run against PyCodeKG's own codebase. See [assessments/](assessments/) for full reports.*
+
+> "PyCodeKG compresses a multi-step workflow — semantic search, graph expansion, caller tracing, snippet retrieval, and architectural summarization — into a small set of tools that are fast to invoke and easy to chain. In practice, it let me move from broad orientation to intent-driven discovery and then to structural validation without dropping down into manual grep or repeated file reads."
+> — GPT-5 (via Cline)
+
+> "What sets it apart from 'search the repo with embeddings' tools is the structural layer… Verdict: 4.5/5 — recommend without reservation for any non-trivial Python codebase."
+> — Claude Opus 4.7
+
+> "PyCodeKG is dramatically more effective than traditional grep/file-reading workflows. Unique value: hybrid search combining natural-language intent with precise structural relationships."
+> — Claude Haiku 4.5
+
+> "`pack_snippets()` provided source excerpts around each hit, making the code instantly readable. Context lines and relevance metadata obviated manual file open."
+> — Raptor Mini
+
+---
+
+## Citation
+
+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)
+
+**APA**
+
+> Suchanek, E. G. (2026). *PyCodeKG: Semantic Knowledge Graph for Python Codebases* (Version 0.18.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19834777
+
+**BibTeX**
+
+```bibtex
+@software{suchanek_pycode_kg,
+  author    = {Suchanek, Eric G.},
+  title     = {{PyCodeKG}: Semantic Knowledge Graph for Python Codebases},
+  version   = {0.18.0},
+  year      = {2026},
+  publisher = {Flux-Frontiers},
+  url       = {https://github.com/Flux-Frontiers/pycode_kg},
+  doi       = {10.5281/zenodo.19834777},
+}
+```
+
+---
+
+## License
+
+[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license) — free for non-commercial and internal use; commercial redistribution or hosting requires a license from Flux-Frontiers.

{pycode_kg-0.17.2 → pycode_kg-0.18.2}/pyproject.toml

@@ -66,7 +66,7 @@ ruff = ">=0.4.0"
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.17.2"
+version = "0.18.2"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"

{pycode_kg-0.17.2 → pycode_kg-0.18.2}/src/pycode_kg/__init__.py

@@ -32,7 +32,7 @@ KGModule SDK (build new domain KGs)::
     from pycode_kg import KGModule, KGExtractor, PyCodeKGExtractor, NodeSpec, EdgeSpec
 """
 
-__version__ = "0.17.2"
+__version__ = "0.18.2"
 __author__ = "Eric G. Suchanek, PhD"
 
 # Low-level primitives (locked v0 contract)

{pycode_kg-0.17.2 → pycode_kg-0.18.2}/src/pycode_kg/analysis/bridge.py

@@ -5,6 +5,7 @@ For well-modularized codebases, identifies orchestrator and hub modules.
 
 Author: Eric G. Suchanek, PhD
 Last Revision: 2026-03-12 17:30:35
+License: Elastic 2.0
 """
 
 import sqlite3
@@ -14,8 +15,11 @@ from pycode_kg.analysis.centrality import CentralityRecord, StructuralImportance
 
 
 def compute_bridge_centrality(
-    kind="module", include_imports=True, top=25, db_path="pycodekg.sqlite"
-):
+    kind: str = "module",
+    include_imports: bool = True,
+    top: int = 25,
+    db_path: str = "pycodekg.sqlite",
+) -> list[tuple[str, float]]:
     """
     Compute module connectivity: unique module interactions per module.
 

{pycode_kg-0.17.2 → pycode_kg-0.18.2}/src/pycode_kg/analysis/centrality.py

@@ -112,6 +112,13 @@ class StructuralImportanceRanker:
     """
 
     def __init__(self, db_path: str | Path, config: CentralityConfig | None = None) -> None:
+        """Bind the ranker to a SQLite graph and (optional) tuning config.
+
+        :param db_path: Path to the PyCodeKG SQLite knowledge graph.
+        :param config: Override default relation weights, damping, iteration
+            cap, tolerance, cross-module boost, or private-symbol penalty.
+            Pass ``None`` for the package defaults (see ``CentralityConfig``).
+        """
         self.db_path = Path(db_path)
         self.config = config or CentralityConfig()
 
@@ -204,6 +211,7 @@ class StructuralImportanceRanker:
         return len(rows)
 
     def _load_nodes(self) -> dict[str, _NodeInfo]:
+        """Load real graph nodes (modules, classes, functions, methods) from SQLite, keyed by node id. ``sym:`` stubs are excluded."""
         with sqlite3.connect(self.db_path) as con:
             rows = con.execute(
                 """
@@ -221,6 +229,11 @@ class StructuralImportanceRanker:
         self,
         node_map: dict[str, _NodeInfo],
     ) -> list[_EffectiveEdge]:
+        """Load structural edges (CALLS / INHERITS / IMPORTS / CONTAINS) and rewrite ``sym:`` targets through ``RESOLVES_TO``.
+
+        Returns deduplicated edges weighted by relation type, with cross-module
+        edges receiving an additional boost from ``config.cross_module_boost``.
+        """
         with sqlite3.connect(self.db_path) as con:
             structural = con.execute(
                 """
@@ -280,6 +293,13 @@ class StructuralImportanceRanker:
         node_map: dict[str, _NodeInfo],
         effective_edges: list[_EffectiveEdge],
     ) -> dict[str, float]:
+        """Run weighted PageRank on the resolved edge set until convergence.
+
+        Iterates up to ``config.max_iter`` with damping ``config.damping``,
+        redistributing dangling-node mass uniformly. After convergence, names
+        starting with ``_`` are scaled by ``config.private_penalty`` and the
+        result is normalized so all scores sum to ``1.0``.
+        """
         nodes = list(node_map)
         n = len(nodes)
         if n == 0:
@@ -329,6 +349,7 @@ class StructuralImportanceRanker:
         effective_edges: list[_EffectiveEdge],
         scores: dict[str, float],
     ) -> list[CentralityRecord]:
+        """Combine PageRank scores with inbound counts, per-relation breakdowns, and top contributing callers into rank-ordered ``CentralityRecord`` outputs."""
         inbound_counts: dict[str, int] = defaultdict(int)
         cross_counts: dict[str, int] = defaultdict(int)
         rel_breakdown: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))

{pycode_kg-0.17.2 → pycode_kg-0.18.2}/src/pycode_kg/analysis/framework_detector.py

@@ -1,6 +1,10 @@
 """
 Framework Detector for PyCodeKG.
 Identifies repo-defining abstractions using centrality and cross-module signals.
+
+Author: Eric G. Suchanek, PhD
+Last Revision: 2026-03-12 17:30:35
+License: Elastic 2.0
 """
 
 import sqlite3
@@ -33,7 +37,9 @@ _BOILERPLATE_NAMES: frozenset[str] = frozenset(
 )
 
 
-def detect_framework_nodes(limit=25, db_path="pycodekg.sqlite"):
+def detect_framework_nodes(
+    limit: int = 25, db_path: str = "pycodekg.sqlite"
+) -> list[tuple[str, float, str]]:
     """
     Detect framework-like nodes using SIR and module connectivity.
 

{pycode_kg-0.17.2 → pycode_kg-0.18.2}/src/pycode_kg/cli/cmd_bridges.py

@@ -8,6 +8,7 @@ from pycode_kg.analysis.bridge import compute_bridge_centrality
 
 
 def main():
+    """CLI entry point: parse args and print top bridge modules by connectivity score to stdout."""
     parser = argparse.ArgumentParser(
         description="Show top bridge modules by betweenness centrality."
     )

{pycode_kg-0.17.2 → pycode_kg-0.18.2}/src/pycode_kg/cli/cmd_framework_nodes.py

@@ -8,6 +8,7 @@ from pycode_kg.analysis.framework_detector import detect_framework_nodes
 
 
 def main():
+    """CLI entry point: parse args and print top framework-like modules (high SIR + high connectivity) to stdout."""
     parser = argparse.ArgumentParser(description="Show top framework-like modules.")
     parser.add_argument("--db", default="pycodekg.sqlite", help="Path to PyCodeKG SQLite DB")
     parser.add_argument("--top", type=int, default=25, help="Number of top framework nodes to show")

{pycode_kg-0.17.2 → pycode_kg-0.18.2}/src/pycode_kg/cli/cmd_viz.py

@@ -88,13 +88,13 @@ def viz(db: str, port: str, no_browser: bool) -> None:
 )
 @click.option(
     "--layout",
-    type=click.Choice(["allium", "cake"]),
+    type=click.Choice(["allium", "funnel"]),
     default="allium",
     show_default=True,
     help=(
         "3-D layout strategy. "
         "'allium' renders each module as a Giant Allium plant; "
-        "'cake' stratifies nodes by kind across Z layers."
+        "'funnel' stratifies nodes by kind across Z layers."
     ),
 )
 @click.option(