pycode-kg 0.19.0__tar.gz → 0.19.2__tar.gz

{pycode_kg-0.19.0 → pycode_kg-0.19.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.19.0
+Version: 0.19.2
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -25,10 +25,9 @@ Requires-Dist: PyQt5 (>=5.15.0) ; extra == "viz3d"
 Requires-Dist: click (>=8.1.0,<9)
 Requires-Dist: detect-secrets (>=1.5.0) ; extra == "all"
 Requires-Dist: detect-secrets (>=1.5.0) ; extra == "dev"
-Requires-Dist: doc-kg (>=0.11.0) ; extra == "dev"
-Requires-Dist: doc-kg (>=0.11.0) ; extra == "kgdeps"
-Requires-Dist: kgmodule-utils (>=0.2.1)
-Requires-Dist: lancedb (>=0.29.0)
+Requires-Dist: doc-kg (>=0.15.2) ; extra == "dev"
+Requires-Dist: doc-kg (>=0.15.2) ; extra == "kgdeps"
+Requires-Dist: kgmodule-utils[semantic] (>=0.3.1)
 Requires-Dist: markdown (>=3.6) ; extra == "all"
 Requires-Dist: markdown (>=3.6) ; extra == "viz3d"
 Requires-Dist: mcp (>=1.0.0)
@@ -66,7 +65,7 @@ Requires-Dist: streamlit (>=1.35.0) ; extra == "viz"
 Requires-Dist: torch (>=2.5.1)
 Requires-Dist: trame-vtk (>=2.0.0) ; extra == "all"
 Requires-Dist: trame-vtk (>=2.0.0) ; extra == "viz3d"
-Requires-Dist: transformers (>=4.57.6)
+Requires-Dist: transformers (>=4.40.0,<4.57)
 Project-URL: Homepage, https://github.com/Flux-Frontiers/pycode_kg
 Project-URL: Repository, https://github.com/Flux-Frontiers/pycode_kg
 Description-Content-Type: text/markdown
@@ -78,7 +77,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.19.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.19.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)
@@ -117,23 +116,40 @@ PyCodeKG is designed to be useful at both ends — as a standalone command-line
 
 ### 1. Standalone — `pycodekg analyze`
 
-This is the bread and butter. One command, one repo, one architectural report:
+This single command is the actual reason I wrote this module. I got tired of my LLM doing grep on my src/ in order to get a good analysis of the codebase. This command runs fifteen analysis passes in seconds and the output drops straight into your favorite coding LLM for targeted improvement suggestions. I used this process to iteratively improve PyCodeKG and several of the analysis passes were added as a result.
+
+The analysis/ has files *_analysis_<date>.md - I ran PyCodeKG against **numpy** and **matplotlib** for fun.
 
 ```bash
+pycodekg init                                        # downloads embedder
 pycodekg build --repo .                              # one-time index
-pycodekg analyze .                                   # the report
+pycodekg analyze.                                    # the full report
 ```
 
-`analyze` walks the graph and produces:
-
-- **Complexity hotspots** — high fan-in (broadly depended on, breaking-change risk) and high fan-out (orchestrators, refactoring candidates) functions, with risk levels
-- **Docstring coverage** — broken down by module, class, function, method
-- **Circular import cycles** — module loops that cause hard-to-debug failures
-- **Orphaned functions** — dead-code candidates with line counts (with caveats about entry points and reflection)
-- **Module coupling** — the import graph, with the most tightly coupled pairs called out
-- **Issues and strengths** — high-level callouts suitable for a design review or release note
-
-It writes a Markdown report for humans and a timestamped JSON snapshot for tooling, CI gates, and trend tracking. Reach for `analyze` before any non-trivial refactor, at every release, and whenever you inherit an unfamiliar codebase. Full reference: [docs/Analyze.md](docs/Analyze.md).
+**Note**
+The first-time run can take some time to warm up. Be patient.
+
+The 15-phase pipeline runs in sequence and surfaces several important metrics:
+
+| # | Phase | What it surfaces |
+|---|-------|-----------------|
+| 1 | Baseline metrics | Node/edge counts, graph shape |
+| 2 | CodeRank (global PageRank) | Structurally most important symbols |
+| 3 | Fan-in analysis | Heavily depended-on functions (breaking-change risk) |
+| 4 | Fan-out analysis | Orchestrators and complexity hotspots |
+| 5 | Dependency analysis | Orphaned / dead code candidates |
+| 6 | Pattern detection | Anti-patterns and structural red flags |
+| 7 | Module coupling | Tightly coupled pairs, import graph density |
+| 8 | Critical paths | Longest call chains, bottlenecks |
+| 9 | Public API identification | Exposed vs. internal surface |
+| 10 | Docstring coverage | By module, class, function, method |
+| 11 | Inheritance hierarchy | Depth, multiple inheritance, diamond patterns |
+| 12 | Insight synthesis | Issues + strengths callouts |
+| 13 | Snapshot history | Metric trends across releases |
+| 14 | Structural centrality (SIR) | Bridge nodes, graph removal impact |
+| 15 | Concern-based ranking | Nodes grouped by architectural concern |
+
+Every finding maps to a file and line number — no hallucinated signatures, no probabilistic guesses. The Markdown output is LLM-ready; the JSON snapshot is CI-gate-ready. Reach for `analyze` before any non-trivial refactor, at every release, and whenever you inherit an unfamiliar codebase. Full reference: [docs/Analyze.md](docs/Analyze.md).
 
 ```bash
 pycodekg analyze --quiet --json ~/.claude/pycodekg_analysis_latest.json
@@ -190,7 +206,7 @@ The graph is built around four node kinds (module, class, function, method) and
 
 ---
 
-## What you can actually do with it
+## What you can do with it
 
 | If you want to… | Reach for | Detail |
 |---|---|---|
@@ -201,7 +217,7 @@ The graph is built around four node kinds (module, class, function, method) and
 | **Pull source-grounded context for an LLM** | `pycodekg pack "..." --format md` | [docs/CHEATSHEET.md](docs/CHEATSHEET.md) |
 | **Run a hybrid semantic + structural query** | `pycodekg query "..."` | [docs/CHEATSHEET.md](docs/CHEATSHEET.md) |
 | **Browse the graph interactively** | `pycodekg viz` (Streamlit) | [docs/INSTALLATION.md](docs/INSTALLATION.md) |
-| **See call graphs in 3-D** | `pycodekg viz3d --layout funnel` | [docs/VIZ3D.md](docs/VIZ3D.md) |
+| **See call graphs in 3-D** *(active development — functional but rough)* | `pycodekg viz3d --layout funnel` | [docs/VIZ3D.md](docs/VIZ3D.md) |
 | **Wire it into Claude / Copilot / Cline** | `pycodekg mcp` | [docs/MCP.md](docs/MCP.md) |
 
 If you only read one doc after this one, read [docs/Analyze.md](docs/Analyze.md) — that's where most of the day-to-day value lives.

{pycode_kg-0.19.0 → pycode_kg-0.19.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.19.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.19.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)
@@ -44,23 +44,40 @@ PyCodeKG is designed to be useful at both ends — as a standalone command-line
 
 ### 1. Standalone — `pycodekg analyze`
 
-This is the bread and butter. One command, one repo, one architectural report:
+This single command is the actual reason I wrote this module. I got tired of my LLM doing grep on my src/ in order to get a good analysis of the codebase. This command runs fifteen analysis passes in seconds and the output drops straight into your favorite coding LLM for targeted improvement suggestions. I used this process to iteratively improve PyCodeKG and several of the analysis passes were added as a result.
+
+The analysis/ has files *_analysis_<date>.md - I ran PyCodeKG against **numpy** and **matplotlib** for fun.
 
 ```bash
+pycodekg init                                        # downloads embedder
 pycodekg build --repo .                              # one-time index
-pycodekg analyze .                                   # the report
+pycodekg analyze.                                    # the full report
 ```
 
-`analyze` walks the graph and produces:
-
-- **Complexity hotspots** — high fan-in (broadly depended on, breaking-change risk) and high fan-out (orchestrators, refactoring candidates) functions, with risk levels
-- **Docstring coverage** — broken down by module, class, function, method
-- **Circular import cycles** — module loops that cause hard-to-debug failures
-- **Orphaned functions** — dead-code candidates with line counts (with caveats about entry points and reflection)
-- **Module coupling** — the import graph, with the most tightly coupled pairs called out
-- **Issues and strengths** — high-level callouts suitable for a design review or release note
-
-It writes a Markdown report for humans and a timestamped JSON snapshot for tooling, CI gates, and trend tracking. Reach for `analyze` before any non-trivial refactor, at every release, and whenever you inherit an unfamiliar codebase. Full reference: [docs/Analyze.md](docs/Analyze.md).
+**Note**
+The first-time run can take some time to warm up. Be patient.
+
+The 15-phase pipeline runs in sequence and surfaces several important metrics:
+
+| # | Phase | What it surfaces |
+|---|-------|-----------------|
+| 1 | Baseline metrics | Node/edge counts, graph shape |
+| 2 | CodeRank (global PageRank) | Structurally most important symbols |
+| 3 | Fan-in analysis | Heavily depended-on functions (breaking-change risk) |
+| 4 | Fan-out analysis | Orchestrators and complexity hotspots |
+| 5 | Dependency analysis | Orphaned / dead code candidates |
+| 6 | Pattern detection | Anti-patterns and structural red flags |
+| 7 | Module coupling | Tightly coupled pairs, import graph density |
+| 8 | Critical paths | Longest call chains, bottlenecks |
+| 9 | Public API identification | Exposed vs. internal surface |
+| 10 | Docstring coverage | By module, class, function, method |
+| 11 | Inheritance hierarchy | Depth, multiple inheritance, diamond patterns |
+| 12 | Insight synthesis | Issues + strengths callouts |
+| 13 | Snapshot history | Metric trends across releases |
+| 14 | Structural centrality (SIR) | Bridge nodes, graph removal impact |
+| 15 | Concern-based ranking | Nodes grouped by architectural concern |
+
+Every finding maps to a file and line number — no hallucinated signatures, no probabilistic guesses. The Markdown output is LLM-ready; the JSON snapshot is CI-gate-ready. Reach for `analyze` before any non-trivial refactor, at every release, and whenever you inherit an unfamiliar codebase. Full reference: [docs/Analyze.md](docs/Analyze.md).
 
 ```bash
 pycodekg analyze --quiet --json ~/.claude/pycodekg_analysis_latest.json
@@ -117,7 +134,7 @@ The graph is built around four node kinds (module, class, function, method) and
 
 ---
 
-## What you can actually do with it
+## What you can do with it
 
 | If you want to… | Reach for | Detail |
 |---|---|---|
@@ -128,7 +145,7 @@ The graph is built around four node kinds (module, class, function, method) and
 | **Pull source-grounded context for an LLM** | `pycodekg pack "..." --format md` | [docs/CHEATSHEET.md](docs/CHEATSHEET.md) |
 | **Run a hybrid semantic + structural query** | `pycodekg query "..."` | [docs/CHEATSHEET.md](docs/CHEATSHEET.md) |
 | **Browse the graph interactively** | `pycodekg viz` (Streamlit) | [docs/INSTALLATION.md](docs/INSTALLATION.md) |
-| **See call graphs in 3-D** | `pycodekg viz3d --layout funnel` | [docs/VIZ3D.md](docs/VIZ3D.md) |
+| **See call graphs in 3-D** *(active development — functional but rough)* | `pycodekg viz3d --layout funnel` | [docs/VIZ3D.md](docs/VIZ3D.md) |
 | **Wire it into Claude / Copilot / Cline** | `pycodekg mcp` | [docs/MCP.md](docs/MCP.md) |
 
 If you only read one doc after this one, read [docs/Analyze.md](docs/Analyze.md) — that's where most of the day-to-day value lives.

{pycode_kg-0.19.0 → pycode_kg-0.19.2}/pyproject.toml

@@ -43,11 +43,6 @@
 requires = ["poetry-core>=2.0.0"]
 build-backend = "poetry.core.masonry.api"
 
-[[tool.poetry.source]]
-name = "testpypi"
-url = "https://test.pypi.org/simple/"
-priority = "supplemental"
-
 [tool.poetry]
 packages = [{ include = "pycode_kg", from = "src" }]
 
@@ -66,7 +61,7 @@ ruff = ">=0.4.0"
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.19.0"
+version = "0.19.2"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"
@@ -86,7 +81,6 @@ classifiers = [
 requires-python = ">=3.12,<3.14"
 dependencies = [
     "click>=8.1.0,<9",
-    "lancedb>=0.29.0",
     "mcp>=1.0.0",
     "numpy>=1.24.0",
     "pandas>=2.0.0",
@@ -94,8 +88,8 @@ dependencies = [
     "safetensors>=0.5.0",
     "sentence-transformers>=5.4.1",
     "torch>=2.5.1",
-    "transformers>=4.57.6",
-    "kgmodule-utils>=0.2.1",
+    "transformers>=4.40.0,<4.57",
+    "kgmodule-utils[semantic]>=0.3.1",
 ]
 
 [project.optional-dependencies]
@@ -108,7 +102,7 @@ dev = [
     "pytest>=8.0.0",
     "pytest-cov>=5.0.0",
     "ruff>=0.4.0",
-    "doc-kg>=0.11.0",
+    "doc-kg>=0.15.2",
     # agent-kg not yet on PyPI — install manually: pip install git+https://github.com/Flux-Frontiers/agent_kg.git
 ]
 viz = [
@@ -127,7 +121,7 @@ viz3d = [
 
 # note that dockg is on pypi; agent-kg is not yet — install manually from git
 kgdeps = [
-    "doc-kg>=0.11.0",
+    "doc-kg>=0.15.2",
 ]
 all = [
     "detect-secrets>=1.5.0",

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

{pycode_kg-0.19.0 → pycode_kg-0.19.2}/src/pycode_kg/cli/cmd_build.py

@@ -16,12 +16,12 @@ import click
 from pycode_kg.cli.main import cli
 from pycode_kg.cli.options import exclude_option, include_option, repo_option
 from pycode_kg.config import load_exclude_dirs, load_include_dirs
-from pycode_kg.graph import CodeGraph
 from pycode_kg.index import (
     SemanticIndex,
     SentenceTransformerEmbedder,
     suppress_ingestion_logging,
 )
+from pycode_kg.module.extractor import EdgeSpec, NodeSpec, PyCodeKGExtractor
 from pycode_kg.pycodekg import DEFAULT_MODEL
 from pycode_kg.store import GraphStore
 
@@ -53,19 +53,25 @@ def build_sqlite(
     include = load_include_dirs(repo_root) | set(include_dir)
     exclude = load_exclude_dirs(repo_root) | set(exclude_dir)
 
-    graph = CodeGraph(
+    extractor = PyCodeKGExtractor(
         repo_root,
         include=include if include else None,
         exclude=exclude if exclude else None,
     )
-    nodes, edges = graph.extract().result()
+    node_specs: list[NodeSpec] = []
+    edge_specs: list[EdgeSpec] = []
+    for item in extractor.extract():
+        if isinstance(item, NodeSpec):
+            node_specs.append(item)
+        else:
+            edge_specs.append(item)
 
     store = GraphStore(db_path)
-    store.write(nodes, edges, wipe=wipe)
+    store.write(node_specs, edge_specs, wipe=wipe)
     resolved = store.resolve_symbols()
     store.close()
 
-    print(f"OK: nodes={len(nodes)} edges={len(edges)} resolved={resolved} db={db_path}")
+    print(f"OK: nodes={len(node_specs)} edges={len(edge_specs)} resolved={resolved} db={db_path}")
 
 
 @cli.command("build-lancedb")

{pycode_kg-0.19.0 → pycode_kg-0.19.2}/src/pycode_kg/cli/cmd_build_full.py

@@ -22,12 +22,12 @@ from pycode_kg.cli.options import (
     repo_option,
 )
 from pycode_kg.config import load_exclude_dirs, load_include_dirs
-from pycode_kg.graph import CodeGraph
 from pycode_kg.index import (
     SemanticIndex,
     SentenceTransformerEmbedder,
     suppress_ingestion_logging,
 )
+from pycode_kg.module.extractor import EdgeSpec, NodeSpec, PyCodeKGExtractor
 from pycode_kg.store import GraphStore
 
 
@@ -126,15 +126,21 @@ def _run_pipeline(
 
     # Step 1: Build graph store
     t1 = time.monotonic()
-    graph = CodeGraph(
+    extractor = PyCodeKGExtractor(
         repo_root,
         include=include if include else None,
         exclude=exclude if exclude else None,
     )
-    nodes, edges = graph.extract().result()
+    node_specs: list[NodeSpec] = []
+    edge_specs: list[EdgeSpec] = []
+    for item in extractor.extract():
+        if isinstance(item, NodeSpec):
+            node_specs.append(item)
+        else:
+            edge_specs.append(item)
 
     store = GraphStore(db_path)
-    store.write(nodes, edges, wipe=wipe)
+    store.write(node_specs, edge_specs, wipe=wipe)
     resolved = store.resolve_symbols()
     store.close()
 
@@ -142,8 +148,8 @@ def _run_pipeline(
         1,
         "graph store",
         [
-            ("nodes", str(len(nodes))),
-            ("edges", str(len(edges))),
+            ("nodes", str(len(node_specs))),
+            ("edges", str(len(edge_specs))),
             ("resolved", str(resolved)),
         ],
         elapsed=time.monotonic() - t1,

{pycode_kg-0.19.0 → pycode_kg-0.19.2}/src/pycode_kg/cli/cmd_init.py

@@ -18,6 +18,7 @@ import tomllib
 from pathlib import Path
 
 import click
+from kg_utils.semantic import _local_model_path
 
 from pycode_kg.cli.cmd_build_full import _run_pipeline
 from pycode_kg.cli.cmd_hooks import _PRE_COMMIT_HOOK
@@ -28,7 +29,6 @@ from pycode_kg.cli.options import (
     model_option,
     repo_option,
 )
-from pycode_kg.index import _local_model_path
 from pycode_kg.kg import PyCodeKG
 from pycode_kg.pycodekg_thorough_analysis import PyCodeKGAnalyzer
 from pycode_kg.snapshots import SnapshotManager

{pycode_kg-0.19.0 → pycode_kg-0.19.2}/src/pycode_kg/cli/cmd_model.py

@@ -9,9 +9,9 @@ CLI command for managing the PyCodeKG embedding model cache.
 from __future__ import annotations
 
 import click
+from kg_utils.semantic import _local_model_path
 
 from pycode_kg.cli.main import cli
-from pycode_kg.index import _local_model_path
 from pycode_kg.pycodekg import DEFAULT_MODEL
 
 

pycode_kg-0.19.2/src/pycode_kg/index.py

@@ -0,0 +1,11 @@
+"""pycode_kg/index.py — Re-exports semantic index from kg_utils.semantic."""
+
+from kg_utils.semantic import (  # noqa: F401
+    DEFAULT_MODEL,
+    Embedder,
+    SeedHit,
+    SemanticIndex,
+    SentenceTransformerEmbedder,
+    resolve_model_path,
+    suppress_ingestion_logging,
+)

pycode_kg-0.19.2/src/pycode_kg/module/base.py

@@ -0,0 +1,33 @@
+"""pycode_kg/module/base.py — KGModule for pycode_kg: thin subclass of kg_utils.pipeline."""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+
+from kg_utils.extractor import KGExtractor
+from kg_utils.pipeline import KGModule as _KGModuleBase
+from kg_utils.store import GraphStore
+
+
+class KGModule(_KGModuleBase):
+    """Abstract base for Python code knowledge graphs.
+
+    Domain authors implement :meth:`make_extractor`, :meth:`kind`, and
+    :meth:`analyze`.  Build/query/pack infrastructure comes from
+    :class:`kg_utils.pipeline.KGModule`.
+    """
+
+    _default_dir: str = ".pycodekg"
+
+    def _post_build_hook(self, store: GraphStore) -> None:
+        """Run symbol resolution after the graph is written."""
+        store.resolve_symbols()
+
+    @abstractmethod
+    def make_extractor(self) -> KGExtractor: ...
+
+    @abstractmethod
+    def kind(self) -> str: ...
+
+    @abstractmethod
+    def analyze(self) -> str: ...

pycode_kg-0.19.2/src/pycode_kg/module/extractor.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+module/extractor.py
+
+KGExtractor — abstract extraction protocol for any knowledge graph domain.
+
+NodeSpec and EdgeSpec are imported from kg_utils.specs and re-exported here.
+PyCodeKGExtractor is the Python-AST-backed implementation.
+
+Author: Eric G. Suchanek, PhD
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+from kg_utils.extractor import KGExtractor  # noqa: F401
+from kg_utils.specs import EdgeSpec, NodeSpec  # noqa: F401
+
+# ---------------------------------------------------------------------------
+# PyCodeKGExtractor — Python-AST-backed extractor
+# ---------------------------------------------------------------------------
+
+
+class PyCodeKGExtractor(KGExtractor):
+    """KGExtractor backed by CodeGraph (Python AST analysis).
+
+    Wraps :class:`~pycode_kg.graph.CodeGraph` and converts its :class:`Node`
+    and :class:`Edge` v0 primitives to :class:`NodeSpec` / :class:`EdgeSpec`
+    for the generic :class:`~pycode_kg.module.base.KGModule` build pipeline.
+
+    This is the extractor used by :class:`~pycode_kg.kg.PyCodeKG` and is the
+    reference implementation for source-code KG extractors.
+
+    :param repo_path: Path to the Python repository root.
+    :param include: Set of top-level directory names to include (all if empty).
+    :param exclude: Set of directory names to exclude at every depth.
+    :param config: Optional config dict (forwarded to super).
+    """
+
+    def __init__(
+        self,
+        repo_path: Path,
+        *,
+        include: set[str] | None = None,
+        exclude: set[str] | None = None,
+        config: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialise the extractor for a Python repository.
+
+        :param repo_path: Path to the Python repository root.
+        :param include: Top-level directory names to include (empty = all).
+        :param exclude: Directory names to exclude at every walk depth.
+        :param config: Optional domain-specific configuration dict.
+        """
+        super().__init__(repo_path, config)
+        self._include: set[str] = include or set()
+        self._exclude: set[str] = exclude or set()
+
+    def node_kinds(self) -> list[str]:
+        """Return the Python AST node kinds.
+
+        :return: ``['module', 'class', 'function', 'method', 'symbol']``
+        """
+        return ["module", "class", "function", "method", "symbol"]
+
+    def edge_kinds(self) -> list[str]:
+        """Return the Python AST edge relation types.
+
+        :return: List of all relation strings emitted by the Python extractor.
+        """
+        return [
+            "CONTAINS",
+            "CALLS",
+            "IMPORTS",
+            "INHERITS",
+            "READS",
+            "WRITES",
+            "ATTR_ACCESS",
+            "DEPENDS_ON",
+            "RESOLVES_TO",
+        ]
+
+    def meaningful_node_kinds(self) -> list[str]:
+        """Return the node kinds indexed by LanceDB and counted in coverage.
+
+        Excludes ``'symbol'`` (unresolved import stubs).
+
+        :return: ``['module', 'class', 'function', 'method']``
+        """
+        return ["module", "class", "function", "method"]
+
+    def extract(self) -> Iterator[NodeSpec | EdgeSpec]:
+        """Run Python AST extraction and yield NodeSpec / EdgeSpec objects.
+
+        Delegates to :class:`~pycode_kg.graph.CodeGraph` for the AST walk, then
+        converts the v0-locked :class:`~pycode_kg.pycodekg.Node` and
+        :class:`~pycode_kg.pycodekg.Edge` primitives to the generic spec types.
+
+        :return: Iterator of :class:`NodeSpec` and :class:`EdgeSpec` objects.
+        """
+        from pycode_kg.graph import CodeGraph  # pylint: disable=import-outside-toplevel
+
+        graph = CodeGraph(self.repo_path, include=self._include, exclude=self._exclude)
+        nodes, edges = graph.result()
+
+        for n in nodes:
+            yield NodeSpec(
+                node_id=n.id,
+                kind=n.kind,
+                name=n.name,
+                qualname=n.qualname or "",
+                source_path=n.module_path or "",
+                lineno=n.lineno,
+                end_lineno=n.end_lineno,
+                docstring=n.docstring or "",
+            )
+
+        for e in edges:
+            yield EdgeSpec(
+                source_id=e.src,
+                target_id=e.dst,
+                relation=e.rel,
+                metadata={"evidence": e.evidence} if e.evidence else {},
+            )

pycode_kg-0.19.2/src/pycode_kg/module/types.py

@@ -0,0 +1,31 @@
+"""pycode_kg/module/types.py — Re-exports from kg_utils for backward compat."""
+
+from dataclasses import dataclass
+
+from kg_utils.pipeline import (  # noqa: F401
+    compute_span,
+    docstring_signal,
+    lexical_overlap_score,
+    make_module_summary,
+    make_snippet,
+    normalize_query_text,
+    query_tokens,
+    read_lines,
+    safe_join,
+    semantic_score_from_distance,
+    spans_overlap,
+)
+from kg_utils.specs import BuildStats, QueryResult, SnippetPack  # noqa: F401
+
+
+@dataclass
+class Snippet:
+    """Backward-compat shim. Snippets are now dicts on node["snippet"]."""
+
+    path: str
+    start: int
+    end: int
+    text: str
+
+    def to_dict(self) -> dict:
+        return {"path": self.path, "start": self.start, "end": self.end, "text": self.text}

{pycode_kg-0.19.0 → pycode_kg-0.19.2}/src/pycode_kg/pycodekg.py

@@ -37,7 +37,8 @@ from pathlib import Path
 # ============================================================================
 # Configuration
 # ============================================================================
-from pycode_kg.index import DEFAULT_MODEL as DEFAULT_MODEL  # noqa: F401 — re-exported
+from kg_utils.semantic import DEFAULT_MODEL as DEFAULT_MODEL  # noqa: F401 — re-exported
+
 from pycode_kg.utils import node_id, rel_module_path
 from pycode_kg.visitor import PyCodeKGVisitor
 

pycode_kg-0.19.2/src/pycode_kg/store.py

@@ -0,0 +1,7 @@
+"""pycode_kg/store.py — Re-exports GraphStore from kg_utils.store."""
+
+from kg_utils.store import (  # noqa: F401
+    DEFAULT_RELS,
+    GraphStore,
+    ProvMeta,
+)