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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.18.1
+Version: 0.18.2
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -78,7 +78,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.18.1-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)
@@ -114,31 +114,13 @@ PyCodeKG uses the same architecture as [DocKG](https://github.com/Flux-Frontiers
 - **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** — Seventeen tools for AI agent integration
+- **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
-
-```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
-```
-
----
-
 ## Installation
 
 **Requirements:** Python ≥ 3.12, < 3.14
@@ -161,6 +143,24 @@ poetry add pycode-kg
 
 ---
 
+## 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
@@ -198,20 +198,6 @@ pycodekg viz-timeline                                # metric history timeline
 
 ---
 
-## MCP Integration
-
-Start the MCP server, then wire it into your AI agent:
-
-```bash
-pycodekg mcp --repo /path/to/repo
-```
-
-PyCodeKG exposes seventeen tools covering hybrid search, snippet packing, caller tracing, architectural analysis, and temporal snapshots. Any MCP-compatible agent — Claude Code, Claude Desktop, Cursor, Continue, GitHub Copilot — can consume them directly.
-
-> Full provider setup, tool reference, and SSE transport: [docs/MCP.md](docs/MCP.md)
-
----
-
 ## What Agents Say
 
 *From independent assessments run against PyCodeKG's own codebase. See [assessments/](assessments/) for full reports.*

{pycode_kg-0.18.1 → pycode_kg-0.18.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.18.1-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)
@@ -41,31 +41,13 @@ PyCodeKG uses the same architecture as [DocKG](https://github.com/Flux-Frontiers
 - **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** — Seventeen tools for AI agent integration
+- **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
-
-```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
-```
-
----
-
 ## Installation
 
 **Requirements:** Python ≥ 3.12, < 3.14
@@ -88,6 +70,24 @@ poetry add pycode-kg
 
 ---
 
+## 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
@@ -125,20 +125,6 @@ pycodekg viz-timeline                                # metric history timeline
 
 ---
 
-## MCP Integration
-
-Start the MCP server, then wire it into your AI agent:
-
-```bash
-pycodekg mcp --repo /path/to/repo
-```
-
-PyCodeKG exposes seventeen tools covering hybrid search, snippet packing, caller tracing, architectural analysis, and temporal snapshots. Any MCP-compatible agent — Claude Code, Claude Desktop, Cursor, Continue, GitHub Copilot — can consume them directly.
-
-> Full provider setup, tool reference, and SSE transport: [docs/MCP.md](docs/MCP.md)
-
----
-
 ## What Agents Say
 
 *From independent assessments run against PyCodeKG's own codebase. See [assessments/](assessments/) for full reports.*

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

@@ -66,7 +66,7 @@ ruff = ">=0.4.0"
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.18.1"
+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.18.1 → 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.18.1"
+__version__ = "0.18.2"
 __author__ = "Eric G. Suchanek, PhD"
 
 # Low-level primitives (locked v0 contract)

{pycode_kg-0.18.1 → 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.18.1 → 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.18.1 → 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.18.1 → pycode_kg-0.18.2}/src/pycode_kg/ranking/cli_rank.py

@@ -16,6 +16,7 @@ from .coderank import (
 
 
 def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Parse CodeRank CLI arguments. Pass ``argv`` to override ``sys.argv`` (used in tests)."""
     parser = argparse.ArgumentParser(description="Compute CodeRank metrics for PyCodeKG graphs.")
     parser.add_argument("--sqlite", required=True, help="Path to PyCodeKG SQLite graph.")
     parser.add_argument("--top", type=int, default=25, help="Number of top results to print.")
@@ -43,6 +44,7 @@ def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
 
 
 def main(argv: Sequence[str] | None = None) -> int:
+    """CLI entry point: compute CodeRank scores, optionally persist them to ``node_metrics``, and print the top results as plain text or JSON. Returns the process exit code."""
     args = parse_args(argv)
     sqlite_path = Path(args.sqlite)
     if not sqlite_path.exists():

{pycode_kg-0.18.1 → pycode_kg-0.18.2}/src/pycode_kg/snapshots.py

@@ -269,6 +269,15 @@ class SnapshotManager(_BaseSnapshotManager):
         db_path: Path | str | None = None,
         package_name: str = "pycode-kg",
     ) -> None:
+        """Initialize the manager rooted at ``snapshots_dir``.
+
+        :param snapshots_dir: Directory where snapshot JSON files live; created
+            on first save if it does not exist.
+        :param db_path: PyCodeKG SQLite graph path; required for collecting
+            per-module node counts during ``capture()``. Optional otherwise.
+        :param package_name: Package name used for version detection in saved
+            snapshots. Defaults to ``"pycode-kg"``.
+        """
         super().__init__(snapshots_dir, package_name=package_name, db_path=db_path)
 
     # ------------------------------------------------------------------
@@ -457,14 +466,17 @@ class SnapshotManager(_BaseSnapshotManager):
     # ------------------------------------------------------------------
 
     def load_snapshot(self, key: str) -> Snapshot | None:  # type: ignore[override]
+        """Load a snapshot by key and re-wrap it as a pycode-kg ``Snapshot`` with typed-accessor properties. Returns ``None`` if no snapshot matches."""
         snap = super().load_snapshot(key)
         return _rewrap(snap) if snap is not None else None
 
     def get_previous(self, key: str) -> Snapshot | None:  # type: ignore[override]
+        """Return the snapshot immediately preceding ``key`` in manifest chronology, re-wrapped as a pycode-kg ``Snapshot``. ``None`` when ``key`` is the earliest."""
         snap = super().get_previous(key)
         return _rewrap(snap) if snap is not None else None
 
     def get_baseline(self) -> Snapshot | None:  # type: ignore[override]
+        """Return the earliest (baseline) snapshot in the manifest, re-wrapped as a pycode-kg ``Snapshot``. ``None`` if no snapshots exist."""
         snap = super().get_baseline()
         return _rewrap(snap) if snap is not None else None
 

pycode_kg-0.18.1/src/pycode_kg/mcp/bridge_tools.py

@@ -1,19 +0,0 @@
-"""
-MCP tool hooks for bridge centrality in PyCodeKG.
-"""
-
-# Placeholder for MCP integration
-
-
-def top_bridges(kind="module", limit=20):
-    from pycode_kg.analysis.bridge import (  # pylint: disable=import-outside-toplevel
-        compute_bridge_centrality,
-    )
-
-    bridges = compute_bridge_centrality(kind=kind, top=limit)
-    return bridges
-
-
-def why_bridge(node_id):
-    # TODO: Explain why a node is a bridge
-    pass

pycode_kg-0.18.1/src/pycode_kg/mcp/framework_tools.py

@@ -1,18 +0,0 @@
-"""
-MCP tool hooks for framework node detection in PyCodeKG.
-"""
-
-# Placeholder for MCP integration
-
-
-def detect_framework_nodes(limit=20):
-    from pycode_kg.analysis.framework_detector import (  # pylint: disable=import-outside-toplevel
-        detect_framework_nodes as detect_fw,
-    )
-
-    return detect_fw(limit=limit)
-
-
-def why_framework_node(node_id):
-    # TODO: Explain why a node is a framework node
-    pass