pycode-kg 0.16.0__py3-none-any.whl

pycode_kg/cli/cmd_init.py

@@ -0,0 +1,312 @@
+"""
+cmd_init.py
+
+CLI command for initializing PyCodeKG in a repository:
+
+  init — download model, build graph, install hooks, capture snapshot
+
+  Author: Eric G. Suchanek, PhD
+"""
+
+from __future__ import annotations
+
+import stat
+import subprocess
+import time
+import tomllib
+from pathlib import Path
+
+import click
+
+from pycode_kg.cli.main import cli
+from pycode_kg.cli.options import (
+    exclude_option,
+    include_option,
+    model_option,
+    repo_option,
+)
+from pycode_kg.index import _local_model_path
+
+
+def _has_pycodekg_config(repo_root: Path) -> bool:
+    """Check whether pyproject.toml already has a [tool.pycodekg] section."""
+    pyproject = repo_root / "pyproject.toml"
+    if not pyproject.exists():
+        return False
+    try:
+        with open(pyproject, "rb") as f:
+            data = tomllib.load(f)
+        return "pycodekg" in data.get("tool", {})
+    except (OSError, ValueError):
+        return False
+
+
+def _scaffold_pycodekg_config(repo_root: Path) -> bool:
+    """Append a minimal [tool.pycodekg] section to pyproject.toml if missing.
+
+    Detects the most likely source directory (``src``, ``lib``, or the
+    project name) and sets it as the include list.
+
+    :param repo_root: Repository root directory.
+    :return: True if the section was added, False if skipped.
+    """
+    pyproject = repo_root / "pyproject.toml"
+    if not pyproject.exists():
+        return False
+
+    # Guess the best include directory
+    candidates = ["src", "lib"]
+    include_dirs: list[str] = [d for d in candidates if (repo_root / d).is_dir()]
+
+    if not include_dirs:
+        # Fall back to the repo name itself if it's a directory
+        repo_name = repo_root.name.replace("-", "_")
+        if (repo_root / repo_name).is_dir():
+            include_dirs = [repo_name]
+
+    lines = [
+        "",
+        "[tool.pycodekg]",
+        "# Directories to include in the knowledge graph build and analysis.",
+        "# When unset, all directories are indexed.",
+    ]
+    if include_dirs:
+        include_str = ", ".join(f'"{d}"' for d in include_dirs)
+        lines.append(f"include = [{include_str}]")
+    else:
+        lines.append("# include = []")
+
+    pyproject.open("a").write("\n".join(lines) + "\n")
+    return True
+
+
+@cli.command("init")
+@repo_option
+@model_option
+@include_option
+@exclude_option
+@click.option("--skip-hooks", is_flag=True, help="Don't install the pre-commit git hook.")
+@click.option("--skip-snapshot", is_flag=True, help="Don't capture an initial snapshot.")
+@click.option("--force", is_flag=True, help="Overwrite existing graph data and hook.")
+@click.option("-v", "--verbose", is_flag=True, help="Show progress details.")
+def init(
+    repo: str,
+    model: str,
+    include_dir: tuple[str, ...],
+    exclude_dir: tuple[str, ...],
+    skip_hooks: bool,
+    skip_snapshot: bool,
+    force: bool,
+    verbose: bool,
+) -> None:
+    """Initialize PyCodeKG in a repository.
+
+    Downloads the embedding model, builds the knowledge graph (SQLite +
+    LanceDB), optionally installs the pre-commit hook, and captures an
+    initial snapshot.  Designed to be idempotent — safe to run more than once.
+
+    Example::
+
+        pycodekg init --repo .
+    """
+    from pycode_kg.cli.cmd_build_full import (
+        _run_pipeline,  # noqa: PLC0415  # pylint: disable=import-outside-toplevel
+    )
+    from pycode_kg.cli.cmd_hooks import (
+        _PRE_COMMIT_HOOK,  # noqa: PLC0415  # pylint: disable=import-outside-toplevel
+    )
+
+    repo_root = Path(repo).resolve()
+    t_total = time.monotonic()
+
+    click.echo()
+    click.echo("  PyCodeKG  Init")
+    click.echo(f"  repo  {repo_root}")
+    click.echo()
+
+    # ------------------------------------------------------------------
+    # Step 0: Scaffold [tool.pycodekg] in pyproject.toml if missing
+    # ------------------------------------------------------------------
+    if not _has_pycodekg_config(repo_root):
+        if _scaffold_pycodekg_config(repo_root):
+            click.echo("  [0/4]  Added [tool.pycodekg] section to pyproject.toml")
+        else:
+            click.echo("  [0/4]  No pyproject.toml found — skipping config scaffold")
+    else:
+        click.echo("  [0/4]  [tool.pycodekg] config already present")
+
+    # ------------------------------------------------------------------
+    # Step 1: Download the embedding model
+    # ------------------------------------------------------------------
+    click.echo()
+    local_path = _local_model_path(model)
+
+    if local_path.exists() and not force:
+        click.echo(f"  [1/4]  Model already cached at {local_path}")
+    else:
+        click.echo(f"  [1/4]  Downloading embedding model '{model}'...")
+        from sentence_transformers import (  # noqa: PLC0415  # pylint: disable=import-outside-toplevel
+            SentenceTransformer,
+        )
+
+        st_model = SentenceTransformer(model)
+        local_path.mkdir(parents=True, exist_ok=True)
+        st_model.save(str(local_path))
+        click.echo(f"         OK: model saved to {local_path}")
+
+    # ------------------------------------------------------------------
+    # Step 2: Build the knowledge graph (full wipe)
+    # ------------------------------------------------------------------
+    click.echo()
+    click.echo("  [2/4]  Building knowledge graph...")
+    _run_pipeline(
+        repo=repo,
+        db=None,
+        lancedb=None,
+        table="pycodekg_nodes",
+        model=model,
+        verbose=verbose,
+        kinds="module,class,function,method",
+        batch=256,
+        include_dir=include_dir,
+        exclude_dir=exclude_dir,
+        wipe=True,
+        label="Init Build",
+    )
+
+    # ------------------------------------------------------------------
+    # Step 3: Install pre-commit hook
+    # ------------------------------------------------------------------
+    click.echo()
+    if skip_hooks:
+        click.echo("  [3/4]  Skipping hook installation (--skip-hooks)")
+    else:
+        git_dir = repo_root / ".git"
+        if not git_dir.is_dir():
+            click.echo("  [3/4]  Not a git repository — skipping hook installation")
+        else:
+            hooks_dir = git_dir / "hooks"
+            hooks_dir.mkdir(exist_ok=True)
+            hook_path = hooks_dir / "pre-commit"
+
+            if hook_path.exists() and not force:
+                click.echo(f"  [3/4]  Hook already exists: {hook_path}")
+                click.echo("         Use --force to overwrite.")
+            else:
+                hook_path.write_text(_PRE_COMMIT_HOOK)
+                mode = hook_path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+                hook_path.chmod(mode)
+                click.echo(f"  [3/4]  OK: installed pre-commit hook at {hook_path}")
+
+    # ------------------------------------------------------------------
+    # Step 4: Capture initial snapshot
+    # ------------------------------------------------------------------
+    click.echo()
+    if skip_snapshot:
+        click.echo("  [4/4]  Skipping initial snapshot (--skip-snapshot)")
+    else:
+        try:
+            tree_hash = (
+                subprocess.check_output(
+                    ["git", "rev-parse", "HEAD"],
+                    cwd=str(repo_root),
+                    stderr=subprocess.DEVNULL,
+                )
+                .decode()
+                .strip()
+            )
+            branch = (
+                subprocess.check_output(
+                    ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                    cwd=str(repo_root),
+                    stderr=subprocess.DEVNULL,
+                )
+                .decode()
+                .strip()
+            )
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            tree_hash = ""
+            branch = "unknown"
+
+        try:
+            import importlib.metadata  # noqa: PLC0415  # pylint: disable=import-outside-toplevel
+
+            from pycode_kg.kg import (
+                PyCodeKG,  # noqa: PLC0415  # pylint: disable=import-outside-toplevel
+            )
+            from pycode_kg.pycodekg_thorough_analysis import (
+                PyCodeKGAnalyzer,  # noqa: PLC0415  # pylint: disable=import-outside-toplevel
+            )
+            from pycode_kg.snapshots import (
+                SnapshotManager,  # noqa: PLC0415  # pylint: disable=import-outside-toplevel
+            )
+            from pycode_kg.store import (
+                GraphStore,  # noqa: PLC0415  # pylint: disable=import-outside-toplevel
+            )
+
+            db_path = repo_root / ".pycodekg" / "graph.sqlite"
+            snapshots_path = repo_root / ".pycodekg" / "snapshots"
+            lancedb_dir = repo_root / ".pycodekg" / "lancedb"
+
+            store = GraphStore(db_path)
+            try:
+                stats = store.stats()
+            finally:
+                store.close()
+
+            kg = PyCodeKG(
+                repo_root=repo_root,
+                db_path=db_path,
+                lancedb_dir=lancedb_dir,
+                model=model,
+            )
+            snap_mgr = SnapshotManager(snapshots_path, db_path=db_path)
+            try:
+                analyzer = PyCodeKGAnalyzer(kg, snapshot_mgr=snap_mgr)
+                analysis = analyzer.run_analysis()
+
+                docstring_cov = analysis.get("docstring_coverage", {})
+                coverage = docstring_cov.get("coverage_pct", 0.0) / 100.0 if docstring_cov else 0.0
+                critical_issues = len(analysis.get("issues", []))
+
+                fn_metrics = analysis.get("function_metrics", {})
+                hotspots = [
+                    {
+                        "name": name,
+                        "callers": m.get("fan_in", 0),
+                        "callees": m.get("fan_out", 0),
+                        "risk_level": m.get("risk_level", "low"),
+                    }
+                    for name, m in list(fn_metrics.items())[:10]
+                ]
+                fan_ins = [m.get("fan_in", 0) for m in fn_metrics.values()]
+                complexity_median = sorted(fan_ins)[len(fan_ins) // 2] if fan_ins else 0.0
+            finally:
+                kg.close()
+
+            version = importlib.metadata.version("pycode-kg")
+            snapshot_obj = snap_mgr.capture(
+                version=version,
+                branch=branch,
+                graph_stats_dict=stats,
+                coverage=coverage,
+                critical_issues=critical_issues,
+                complexity_median=complexity_median,
+                hotspots=hotspots,
+                issues=analysis.get("issues", []),
+                tree_hash=tree_hash,
+            )
+            snap_mgr.save_snapshot(snapshot_obj)
+            click.echo(f"  [4/4]  OK: snapshot saved (key={snapshot_obj.key[:12]})")
+        except Exception as exc:  # noqa: BLE001  # pylint: disable=broad-exception-caught
+            click.echo(f"  [4/4]  Snapshot skipped: {exc}", err=True)
+
+    # ------------------------------------------------------------------
+    # Done
+    # ------------------------------------------------------------------
+    elapsed = time.monotonic() - t_total
+    click.echo()
+    click.echo(f"  Done ({elapsed:.1f}s)")
+    click.echo()
+    click.echo("  Run 'pycodekg query \"your question\"' to search the codebase.")
+    click.echo()

pycode_kg/cli/cmd_mcp.py

@@ -0,0 +1,71 @@
+"""
+cmd_mcp.py
+
+Click subcommand for starting the PyCodeKG MCP server:
+
+  mcp  — start the MCP server (thin wrapper around mcp_server.main)
+"""
+
+from __future__ import annotations
+
+import click
+
+from pycode_kg.cli.main import cli
+from pycode_kg.pycodekg import DEFAULT_MODEL
+
+
+@cli.command("mcp")
+@click.option(
+    "--repo",
+    default=".",
+    type=click.Path(exists=True, file_okay=False),
+    help="Repository root directory.",
+)
+@click.option(
+    "--db",
+    default=".pycodekg/graph.sqlite",
+    type=click.Path(),
+    help="SQLite database path.",
+)
+@click.option(
+    "--lancedb",
+    default=".pycodekg/lancedb",
+    type=click.Path(),
+    help="LanceDB directory path.",
+)
+@click.option(
+    "--model",
+    default=DEFAULT_MODEL,
+    help="Sentence-transformer model name.",
+)
+@click.option(
+    "--transport",
+    type=click.Choice(["stdio", "sse"]),
+    default="stdio",
+    help="MCP transport protocol.",
+)
+def mcp(repo: str, db: str, lancedb: str, model: str, transport: str) -> None:
+    """Start the PyCodeKG MCP server."""
+    try:
+        from mcp.server.fastmcp import (  # pylint: disable=import-outside-toplevel
+            FastMCP,  # noqa: F401
+        )
+    except ImportError:
+        raise click.ClickException("'mcp' package not found. Install with: pip install mcp")
+
+    argv = [
+        "--repo",
+        repo,
+        "--db",
+        db,
+        "--lancedb",
+        lancedb,
+        "--model",
+        model,
+        "--transport",
+        transport,
+    ]
+
+    from pycode_kg.mcp_server import main  # pylint: disable=import-outside-toplevel
+
+    main(argv=argv)

pycode_kg/cli/cmd_model.py

@@ -0,0 +1,53 @@
+"""
+cmd_model.py
+
+CLI command for managing the PyCodeKG embedding model cache.
+
+  download-model   — download and cache the sentence-transformer model for offline use
+"""
+
+from __future__ import annotations
+
+import click
+
+from pycode_kg.cli.main import cli
+from pycode_kg.index import _local_model_path
+from pycode_kg.pycodekg import DEFAULT_MODEL
+
+
+@cli.command("download-model")
+@click.option(
+    "--model",
+    default=DEFAULT_MODEL,
+    show_default=True,
+    help="SentenceTransformer model name to download.",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Re-download even if a local copy already exists.",
+)
+def download_model(model: str, force: bool) -> None:
+    """Download and cache the embedding model for offline use.
+
+    The model is saved to ``.pycodekg/models/<model>/`` in the current working
+    directory (or the path set by the ``PYCODEKG_MODEL_DIR`` environment
+    variable).  Once cached, ``pycodekg build-lancedb`` and ``pycodekg query``
+    will use this local copy without any network access.
+    """
+    from sentence_transformers import (  # pylint: disable=import-outside-toplevel
+        SentenceTransformer,
+    )
+
+    local_path = _local_model_path(model)
+
+    if local_path.exists() and not force:
+        click.echo(f"Model already cached at {local_path}")
+        click.echo("Use --force to re-download.")
+        return
+
+    click.echo(f"Downloading model '{model}'...")
+    st_model = SentenceTransformer(model)
+    local_path.mkdir(parents=True, exist_ok=True)
+    st_model.save(str(local_path))
+    click.echo(f"OK: model saved to {local_path}")

pycode_kg/cli/cmd_query.py

@@ -0,0 +1,211 @@
+"""
+cmd_query.py
+
+Click subcommands for querying and packing snippets from the PyCodeKG:
+
+  query   — hybrid semantic + graph query, prints a ranked result summary
+  pack    — hybrid query + source-grounded snippet packing, outputs markdown or JSON
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from pycode_kg.cli.main import cli
+from pycode_kg.cli.options import lancedb_option, model_option, sqlite_option
+from pycode_kg.kg import PyCodeKG
+from pycode_kg.store import DEFAULT_RELS
+
+_DEFAULT_RELS_STR = ",".join(DEFAULT_RELS)
+
+
+@cli.command("query")
+@click.argument("query_text", metavar="QUERY")
+@sqlite_option
+@lancedb_option
+@click.option(
+    "--table",
+    default="pycodekg_nodes",
+    show_default=True,
+    help="LanceDB table name.",
+)
+@model_option
+@click.option("--k", type=int, default=8, show_default=True, help="Top-k semantic hits.")
+@click.option("--hop", type=int, default=1, show_default=True, help="Graph expansion hops.")
+@click.option(
+    "--rels",
+    default=_DEFAULT_RELS_STR,
+    show_default=True,
+    help="Comma-separated edge types to expand.",
+)
+@click.option("--include-symbols", is_flag=True, help="Include symbol nodes in output.")
+def query(
+    query_text: str,
+    sqlite: str,
+    lancedb: str,
+    table: str,
+    model: str,
+    k: int,
+    hop: int,
+    rels: str,
+    include_symbols: bool,
+) -> None:
+    """Run a hybrid semantic + graph query and print a ranked result summary.
+
+    Performs vector-similarity seeding followed by graph expansion to find the
+    most relevant nodes (modules, classes, functions, methods) in the knowledge
+    graph, then prints a ranked summary table to stdout.
+
+    :param query_text: Natural-language query, e.g. ``"database connection setup"``.
+    :param sqlite: Path to the SQLite graph database.
+    :param lancedb: Directory for the LanceDB vector index.
+    :param table: LanceDB table name (default ``pycodekg_nodes``).
+    :param model: Sentence-transformer embedding model name.
+    :param k: Number of semantic seed nodes (default 8).
+    :param hop: Graph expansion hops from each seed (default 1).
+    :param rels: Comma-separated edge types to follow during expansion.
+    :param include_symbols: When set, include low-level symbol nodes in results.
+    """
+    rels_tuple = tuple(r.strip() for r in rels.split(",") if r.strip())
+
+    # query-only does not need repo_root for source reading; use sqlite parent as placeholder
+    repo_root = Path(sqlite).parent
+
+    kg = PyCodeKG(
+        repo_root=repo_root,
+        db_path=Path(sqlite),
+        lancedb_dir=Path(lancedb),
+        model=model,
+        table=table,
+    )
+
+    result = kg.query(
+        query_text,
+        k=k,
+        hop=hop,
+        rels=rels_tuple,
+        include_symbols=include_symbols,
+    )
+    result.print_summary()
+    kg.close()
+
+
+@cli.command("pack")
+@click.argument("query_text", metavar="QUERY")
+@click.option(
+    "--repo-root",
+    default=".",
+    type=click.Path(),
+    show_default=True,
+    help="Repository root directory.",
+)
+@sqlite_option
+@lancedb_option
+@click.option(
+    "--table",
+    default="pycodekg_nodes",
+    show_default=True,
+    help="LanceDB table name.",
+)
+@model_option
+@click.option("--k", type=int, default=8, show_default=True, help="Top-k semantic hits.")
+@click.option("--hop", type=int, default=1, show_default=True, help="Graph expansion hops.")
+@click.option(
+    "--rels",
+    default=_DEFAULT_RELS_STR,
+    show_default=True,
+    help="Comma-separated edge types to expand.",
+)
+@click.option("--include-symbols", is_flag=True, help="Include symbol nodes.")
+@click.option(
+    "--context",
+    type=int,
+    default=5,
+    show_default=True,
+    help="Extra context lines before/after each definition span.",
+)
+@click.option(
+    "--max-lines",
+    type=int,
+    default=160,
+    show_default=True,
+    help="Max lines per snippet block.",
+)
+@click.option(
+    "--max-nodes",
+    type=int,
+    default=None,
+    help="Max nodes returned in pack (default: no limit).",
+)
+@click.option(
+    "--out",
+    type=click.Path(),
+    default=None,
+    help="Output file path (default: stdout).",
+)
+def pack(
+    query_text: str,
+    repo_root: str,
+    sqlite: str,
+    lancedb: str,
+    table: str,
+    model: str,
+    k: int,
+    hop: int,
+    rels: str,
+    include_symbols: bool,
+    context: int,
+    max_lines: int,
+    max_nodes: int | None,
+    out: str | None,
+) -> None:
+    """Run a hybrid query and emit source-grounded snippet packs.
+
+    Performs vector-similarity seeding, graph expansion, and source snippet
+    extraction, then outputs a Markdown context pack with ranked, deduplicated
+    code snippets and line numbers — ready for direct LLM ingestion.
+
+    :param query_text: Natural-language query, e.g. ``"configuration loading"``.
+    :param repo_root: Repository root directory used for source file lookup.
+    :param sqlite: Path to the SQLite graph database.
+    :param lancedb: Directory for the LanceDB vector index.
+    :param table: LanceDB table name (default ``pycodekg_nodes``).
+    :param model: Sentence-transformer embedding model name.
+    :param k: Number of semantic seed nodes (default 8).
+    :param hop: Graph expansion hops from each seed (default 1).
+    :param rels: Comma-separated edge types to follow during expansion.
+    :param include_symbols: When set, include low-level symbol nodes.
+    :param context: Extra context lines before/after each definition span.
+    :param max_lines: Maximum lines per snippet block (default 160).
+    :param max_nodes: Maximum nodes to include in the pack (``None`` for no limit).
+    :param out: Output file path; when omitted, writes to stdout.
+    """
+    rels_tuple = tuple(r.strip() for r in rels.split(",") if r.strip())
+
+    kg = PyCodeKG(
+        repo_root=Path(repo_root),
+        db_path=Path(sqlite),
+        lancedb_dir=Path(lancedb),
+        model=model,
+        table=table,
+    )
+
+    snippet_pack = kg.pack(
+        query_text,
+        k=k,
+        hop=hop,
+        rels=rels_tuple,
+        include_symbols=include_symbols,
+        context=context,
+        max_lines=max_lines,
+        max_nodes=max_nodes,
+    )
+    kg.close()
+
+    if out:
+        snippet_pack.save(out)
+        print(f"OK: wrote pack to {out}")
+    else:
+        print(snippet_pack.to_markdown())