pycode-kg 0.19.1__tar.gz → 0.19.3__tar.gz

{pycode_kg-0.19.1 → pycode_kg-0.19.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.19.1
+Version: 0.19.3
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -25,15 +25,12 @@ 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)
-Requires-Dist: mypy (>=1.10.0) ; extra == "all"
-Requires-Dist: mypy (>=1.10.0) ; extra == "dev"
 Requires-Dist: numpy (>=1.24.0)
 Requires-Dist: pandas (>=2.0.0)
 Requires-Dist: param (>=2.0.0) ; extra == "all"
@@ -67,6 +64,8 @@ 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.40.0,<4.57)
+Requires-Dist: ty (>=0.0.41) ; extra == "all"
+Requires-Dist: ty (>=0.0.41) ; extra == "dev"
 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.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.19.3-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)

{pycode_kg-0.19.1 → pycode_kg-0.19.3}/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.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.19.3-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)

{pycode_kg-0.19.1 → pycode_kg-0.19.3}/pyproject.toml

@@ -7,7 +7,7 @@
 #
 # Quick install (pip)
 # -------------------
-#   pip install -e ".[dev]"             core + dev tools (pytest, ruff, mypy, etc.)
+#   pip install -e ".[dev]"             core + dev tools (pytest, ruff, ty, etc.)
 #   pip install -e ".[viz]"             core + Streamlit/Plotly/PyVis visualizer
 #   pip install -e ".[viz3d]"           core + PyVista 3D visualizer
 #   pip install -e ".[kgdeps]"          core + KG integrations (doc-kg, agent-kg)
@@ -43,17 +43,12 @@
 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" }]
 
 [tool.poetry.group.dev.dependencies]
 detect-secrets = ">=1.5.0"
-mypy = ">=1.10.0"
+ty = "^0.0.41"
 pdoc = ">=14.0.0"
 pre-commit = ">=4.5.1"
 pylint = ">=4.0.5"
@@ -66,7 +61,7 @@ ruff = ">=0.4.0"
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.19.1"
+version = "0.19.3"
 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",
@@ -95,20 +89,20 @@ dependencies = [
     "sentence-transformers>=5.4.1",
     "torch>=2.5.1",
     "transformers>=4.40.0,<4.57",
-    "kgmodule-utils>=0.2.1",
+    "kgmodule-utils[semantic]>=0.3.1",
 ]
 
 [project.optional-dependencies]
 dev = [
     "detect-secrets>=1.5.0",
-    "mypy>=1.10.0",
+    "ty>=0.0.41",
     "pdoc>=14.0.0",
     "pre-commit>=4.5.1",
     "pylint>=4.0.5",
     "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,12 +121,11 @@ 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",
     "markdown>=3.6",
-    "mypy>=1.10.0",
     "param>=2.0.0",
     "pdoc>=14.0.0",
     "plotly>=5.14.0",
@@ -147,6 +140,7 @@ all = [
     "ruff>=0.4.0",
     "streamlit>=1.35.0",
     "trame-vtk>=2.0.0",
+    "ty>=0.0.41",
 ]
 
 [project.urls]
@@ -183,12 +177,19 @@ target-version = "py312"
 select = ["E", "F", "W", "I", "UP"]
 ignore = ["E501"]
 
-[tool.mypy]
-python_version        = "3.12"
-strict                = false
-ignore_missing_imports = true
-mypy_path             = "src"
-explicit_package_bases = true
+[tool.ty.environment]
+python-version = "3.12"
+root = ["src"]
+
+[tool.ty.rules]
+# Be lenient about third-party stubs (mirrors mypy's ignore_missing_imports).
+unresolved-import = "ignore"
+# viz3d.py carries `# ty: ignore` suppressions for param/PyQt5/pyvista false
+# positives. Those libraries live in the optional viz/viz3d extras, so in the
+# lean CI install the imports are Unknown, the errors don't fire, and the
+# ignores look "unused". Don't fail the build on that — the suppressions are
+# still honored locally where the extras (and the errors) are present.
+unused-ignore-comment = "ignore"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{pycode_kg-0.19.1 → pycode_kg-0.19.3}/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.1"
+__version__ = "0.19.3"
 __author__ = "Eric G. Suchanek, PhD"
 
 # Low-level primitives (locked v0 contract)

{pycode_kg-0.19.1 → pycode_kg-0.19.3}/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.1 → pycode_kg-0.19.3}/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.1 → pycode_kg-0.19.3}/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.1 → pycode_kg-0.19.3}/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.1 → pycode_kg-0.19.3}/src/pycode_kg/graph.py

@@ -78,14 +78,16 @@ class CodeGraph:
         """Extracted nodes (calls :meth:`extract` if needed)."""
         if self._nodes is None:
             self.extract()
-        return self._nodes  # type: ignore[return-value]
+        assert self._nodes is not None
+        return self._nodes
 
     @property
     def edges(self) -> list[Edge]:
         """Extracted edges (calls :meth:`extract` if needed)."""
         if self._edges is None:
             self.extract()
-        return self._edges  # type: ignore[return-value]
+        assert self._edges is not None
+        return self._edges
 
     def result(self) -> tuple[list[Node], list[Edge]]:
         """Return the extracted nodes and edges as a tuple.
@@ -120,6 +122,6 @@ class CodeGraph:
         if extracted:
             return (
                 f"CodeGraph(repo_root={self.repo_root!r}, "
-                f"nodes={len(self._nodes)}, edges={len(self._edges)})"  # type: ignore[arg-type]
+                f"nodes={len(self._nodes)}, edges={len(self._edges)})"  # ty: ignore[invalid-argument-type]
             )
         return f"CodeGraph(repo_root={self.repo_root!r}, not yet extracted)"

pycode_kg-0.19.3/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.3/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.3/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.3/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.1 → pycode_kg-0.19.3}/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.1 → pycode_kg-0.19.3}/src/pycode_kg/snapshots.py

@@ -284,7 +284,7 @@ class SnapshotManager(_BaseSnapshotManager):
     # capture — backwards-compat wrapper
     # ------------------------------------------------------------------
 
-    def capture(  # type: ignore[override]
+    def capture(  # ty: ignore[invalid-method-override]
         self,
         version: str | None = None,
         branch: str | None = None,

pycode_kg-0.19.3/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,
+)