pycode-kg 0.16.0__py3-none-any.whl

pycode_kg/viz3d_timeline.py

@@ -0,0 +1,364 @@
+"""
+viz3d_timeline.py — Temporal Metrics Visualization for PyCodeKG Snapshots
+
+Visualizes codebase metrics evolution across commits using 3D plotting.
+Shows trends in nodes, edges, coverage, and critical issues over time.
+
+Features:
+  - Interactive 3D line charts for metric trends
+  - Side-by-side comparison of multiple metrics
+  - Commit-based X-axis with version labels
+  - Color-coded risk assessment (green→yellow→red)
+  - Hover tooltips with snapshot details
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import plotly.graph_objects as go
+import plotly.subplots as subplots
+
+from pycode_kg.snapshots import SnapshotManager
+
+
+def load_snapshots_timeline(snapshots_dir: Path) -> dict[str, Any]:
+    """
+    Load all snapshots and extract timeline data.
+
+    :param snapshots_dir: Path to .pycodekg/snapshots/
+    :return: Dict with timeline data indexed by metric name.
+    """
+    mgr = SnapshotManager(snapshots_dir)
+    snapshots = mgr.list_snapshots()  # Chronological order
+
+    if not snapshots:
+        return {}
+
+    # Extract timeline data
+    timeline: dict[str, list[Any]] = {
+        "commits": [],
+        "versions": [],
+        "timestamps": [],
+        "nodes": [],
+        "edges": [],
+        "coverage": [],
+        "critical_issues": [],
+        "complexity_median": [],
+    }
+
+    for snap in snapshots:
+        timeline["commits"].append(snap["commit"][:7])  # Short hash
+        timeline["versions"].append(snap["version"])
+        timeline["timestamps"].append(snap["timestamp"])
+        timeline["nodes"].append(snap["metrics"]["nodes"])
+        timeline["edges"].append(snap["metrics"]["edges"])
+        timeline["coverage"].append(snap["metrics"]["coverage"] * 100)  # Percentage
+        timeline["critical_issues"].append(snap["metrics"]["critical_issues"])
+        timeline["complexity_median"].append(snap.get("metrics", {}).get("complexity_median", 0))
+
+    return timeline
+
+
+def create_timeline_figure(snapshots_dir: Path) -> go.Figure:
+    """
+    Create interactive 3D timeline visualization.
+
+    Shows 4 metrics:
+    1. Nodes (absolute count)
+    2. Edges (absolute count)
+    3. Coverage (percentage)
+    4. Critical Issues (count)
+
+    :param snapshots_dir: Path to .pycodekg/snapshots/
+    :return: Plotly Figure ready for display.
+    """
+    timeline = load_snapshots_timeline(snapshots_dir)
+
+    if not timeline["commits"]:
+        return go.Figure().add_annotation(text="No snapshots found")
+
+    # Create subplot figure with 2x2 layout
+    fig = subplots.make_subplots(
+        rows=2,
+        cols=2,
+        subplot_titles=("Total Nodes", "Total Edges", "Docstring Coverage %", "Critical Issues"),
+        specs=[
+            [{"secondary_y": False}, {"secondary_y": False}],
+            [{"secondary_y": False}, {"secondary_y": False}],
+        ],
+        vertical_spacing=0.15,
+        horizontal_spacing=0.12,
+    )
+
+    # Hover text for all traces
+    hover_text = [
+        f"<b>{v}</b> ({c})<br>Timestamp: {t}"
+        for v, c, t in zip(timeline["versions"], timeline["commits"], timeline["timestamps"])
+    ]
+
+    # 1. Total Nodes (green trend)
+    fig.add_trace(
+        go.Scatter(
+            x=timeline["commits"],
+            y=timeline["nodes"],
+            mode="lines+markers",
+            name="Nodes",
+            line=dict(color="#22c55e", width=3),
+            marker=dict(size=8),
+            hovertemplate="<b>Nodes:</b> %{y}<br>" + "%{customdata}<extra></extra>",
+            customdata=hover_text,
+        ),
+        row=1,
+        col=1,
+    )
+
+    # 2. Total Edges (blue trend)
+    fig.add_trace(
+        go.Scatter(
+            x=timeline["commits"],
+            y=timeline["edges"],
+            mode="lines+markers",
+            name="Edges",
+            line=dict(color="#3b82f6", width=3),
+            marker=dict(size=8),
+            hovertemplate="<b>Edges:</b> %{y}<br>" + "%{customdata}<extra></extra>",
+            customdata=hover_text,
+        ),
+        row=1,
+        col=2,
+    )
+
+    # 3. Coverage % (cyan trend, with target line)
+    fig.add_trace(
+        go.Scatter(
+            x=timeline["commits"],
+            y=timeline["coverage"],
+            mode="lines+markers",
+            name="Coverage %",
+            line=dict(color="#06b6d4", width=3),
+            marker=dict(size=8),
+            hovertemplate="<b>Coverage:</b> %{y:.1f}%<br>" + "%{customdata}<extra></extra>",
+            customdata=hover_text,
+        ),
+        row=2,
+        col=1,
+    )
+
+    # Add 90% target line for coverage
+    fig.add_hline(
+        y=90,
+        line_dash="dash",
+        line_color="orange",
+        annotation_text="90% Target",
+        row=2,
+        col=1,
+    )
+
+    # 4. Critical Issues (red risk indicator, lower is better)
+    fig.add_trace(
+        go.Scatter(
+            x=timeline["commits"],
+            y=timeline["critical_issues"],
+            mode="lines+markers",
+            name="Critical Issues",
+            line=dict(color="#ef4444", width=3),
+            marker=dict(size=8),
+            hovertemplate="<b>Issues:</b> %{y}<br>" + "%{customdata}<extra></extra>",
+            customdata=hover_text,
+        ),
+        row=2,
+        col=2,
+    )
+
+    # Update layout
+    fig.update_layout(
+        title_text="<b>PyCodeKG Temporal Metrics Evolution</b><br><sub>Snapshots across commits</sub>",
+        title_font_size=20,
+        height=800,
+        width=1400,
+        hovermode="x unified",
+        template="plotly_dark",
+        showlegend=False,
+    )
+
+    # Update X axes
+    for i in range(1, 5):
+        row = (i - 1) // 2 + 1
+        col = (i - 1) % 2 + 1
+        fig.update_xaxes(title_text="Commit", row=row, col=col)
+
+    # Update Y axes
+    fig.update_yaxes(title_text="Count", row=1, col=1)
+    fig.update_yaxes(title_text="Count", row=1, col=2)
+    fig.update_yaxes(title_text="Percentage", row=2, col=1)
+    fig.update_yaxes(title_text="Count", row=2, col=2)
+
+    return fig
+
+
+def create_3d_timeline_figure(snapshots_dir: Path) -> go.Figure:
+    """
+    Create 3D surface plot showing metrics evolution.
+
+    X: Commit index
+    Y: Metric value (normalized)
+    Z: Different metrics stacked
+
+    :param snapshots_dir: Path to .pycodekg/snapshots/
+    :return: Plotly 3D Figure.
+    """
+    timeline = load_snapshots_timeline(snapshots_dir)
+
+    if not timeline["commits"]:
+        return go.Figure().add_annotation(text="No snapshots found")
+
+    # Normalize metrics to 0-100 scale for comparison
+    max_nodes = max(timeline["nodes"]) if timeline["nodes"] else 100
+    max_edges = max(timeline["edges"]) if timeline["edges"] else 100
+    max_issues = max(timeline["critical_issues"]) if timeline["critical_issues"] else 1
+
+    normalized_nodes = [n / max_nodes * 100 for n in timeline["nodes"]]
+    normalized_edges = [e / max_edges * 100 for e in timeline["edges"]]
+    normalized_coverage = timeline["coverage"]  # Already 0-100
+    normalized_issues = [i / max_issues * 100 for i in timeline["critical_issues"]]
+
+    fig = go.Figure()
+
+    # Commit indices for X axis
+    commits_idx = list(range(len(timeline["commits"])))
+
+    # Add surface traces for each metric
+    # Nodes (green)
+    fig.add_trace(
+        go.Scatter3d(
+            x=commits_idx,
+            y=normalized_nodes,
+            z=[0] * len(commits_idx),
+            mode="lines+markers",
+            name="Nodes (normalized)",
+            line=dict(color="#22c55e", width=4),
+            marker=dict(size=6),
+            hovertemplate="<b>Commit:</b> %{customdata}<br><b>Nodes:</b> %{y:.0f}%<extra></extra>",
+            customdata=timeline["commits"],
+        )
+    )
+
+    # Edges (blue)
+    fig.add_trace(
+        go.Scatter3d(
+            x=commits_idx,
+            y=normalized_edges,
+            z=[1] * len(commits_idx),
+            mode="lines+markers",
+            name="Edges (normalized)",
+            line=dict(color="#3b82f6", width=4),
+            marker=dict(size=6),
+            hovertemplate="<b>Commit:</b> %{customdata}<br><b>Edges:</b> %{y:.0f}%<extra></extra>",
+            customdata=timeline["commits"],
+        )
+    )
+
+    # Coverage (cyan)
+    fig.add_trace(
+        go.Scatter3d(
+            x=commits_idx,
+            y=normalized_coverage,
+            z=[2] * len(commits_idx),
+            mode="lines+markers",
+            name="Coverage %",
+            line=dict(color="#06b6d4", width=4),
+            marker=dict(size=6),
+            hovertemplate="<b>Commit:</b> %{customdata}<br><b>Coverage:</b> %{y:.0f}%<extra></extra>",
+            customdata=timeline["commits"],
+        )
+    )
+
+    # Critical Issues (red - inverted so lower is up)
+    fig.add_trace(
+        go.Scatter3d(
+            x=commits_idx,
+            y=[100 - v for v in normalized_issues],  # Invert so lower is better (up)
+            z=[3] * len(commits_idx),
+            mode="lines+markers",
+            name="Health (inverse issues)",
+            line=dict(color="#ef4444", width=4),
+            marker=dict(size=6),
+            hovertemplate="<b>Commit:</b> %{customdata}<br><b>Health:</b> %{y:.0f}%<extra></extra>",
+            customdata=timeline["commits"],
+        )
+    )
+
+    fig.update_layout(
+        title="<b>PyCodeKG 3D Temporal Metrics</b><br><sub>Evolution across commits</sub>",
+        scene=dict(
+            xaxis_title="Commit Index",
+            yaxis_title="Metric (0-100%)",
+            zaxis=dict(
+                title="Metric Type",
+                tickvals=[0, 1, 2, 3],
+                ticktext=["Nodes", "Edges", "Coverage", "Health"],
+            ),
+            camera=dict(
+                eye=dict(x=1.5, y=1.5, z=1.3),
+            ),
+        ),
+        width=1200,
+        height=800,
+        template="plotly_dark",
+        hovermode="closest",
+    )
+
+    return fig
+
+
+def display_timeline_summary(snapshots_dir: Path) -> str:
+    """
+    Generate text summary of timeline metrics.
+
+    :param snapshots_dir: Path to .pycodekg/snapshots/
+    :return: Formatted summary string.
+    """
+    timeline = load_snapshots_timeline(snapshots_dir)
+
+    if not timeline["commits"]:
+        return "No snapshots found"
+
+    # Calculate deltas
+    nodes_delta = timeline["nodes"][-1] - timeline["nodes"][0]
+    edges_delta = timeline["edges"][-1] - timeline["edges"][0]
+    coverage_delta = timeline["coverage"][-1] - timeline["coverage"][0]
+    issues_delta = timeline["critical_issues"][-1] - timeline["critical_issues"][0]
+
+    summary = f"""
++================================================================+
+|         PyCodeKG Temporal Metrics Summary                        |
++================================================================+
+| Snapshots Captured: {len(timeline["commits"]):<41} |
+| Time Range: {timeline["commits"][0]} → {timeline["commits"][-1]:<44} |
+| Versions: {timeline["versions"][0]} → {timeline["versions"][-1]:<48} |
++================================================================+
+| NODES:                                                         |
+|   First:   {timeline["nodes"][0]:<47} |
+|   Latest:  {timeline["nodes"][-1]:<47} |
+|   Δ:       {nodes_delta:+d:<46} |
++================================================================+
+| EDGES:                                                         |
+|   First:   {timeline["edges"][0]:<47} |
+|   Latest:  {timeline["edges"][-1]:<47} |
+|   Δ:       {edges_delta:+d:<46} |
++================================================================+
+| DOCSTRING COVERAGE:                                            |
+|   First:   {timeline["coverage"][0]:.1f}%<{45} |
+|   Latest:  {timeline["coverage"][-1]:.1f}%<{45} |
+|   Δ:       {coverage_delta:+.1f}%<{44} |
++================================================================+
+| CRITICAL ISSUES:                                               |
+|   First:   {timeline["critical_issues"][0]:<47} |
+|   Latest:  {timeline["critical_issues"][-1]:<47} |
+|   Δ:       {issues_delta:+d:<46} |
+|   Trend:   {"Improving" if issues_delta <= 0 else "Regressing":<43} |
++================================================================+
+"""
+    return summary

pycode_kg-0.16.0.dist-info/METADATA

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: pycode-kg
+Version: 0.16.0
+Summary: A tool to build a searchable knowledge graph from Python repositories
+License-Expression: Elastic-2.0
+License-File: LICENSE
+Keywords: knowledge-graph,code-analysis,ast,lancedb,sqlite,semantic-search
+Author: Eric G. Suchanek, PhD
+Author-email: suchanek@mac.com
+Requires-Python: >=3.12,<3.14
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: all
+Provides-Extra: dev
+Provides-Extra: kgdeps
+Provides-Extra: viz
+Provides-Extra: viz3d
+Requires-Dist: PyQt5 (>=5.15.0) ; extra == "all"
+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: kg-snapshot (>=0.3.0)
+Requires-Dist: lancedb (>=0.29.0)
+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"
+Requires-Dist: param (>=2.0.0) ; extra == "viz3d"
+Requires-Dist: pdoc (>=14.0.0) ; extra == "all"
+Requires-Dist: pdoc (>=14.0.0) ; extra == "dev"
+Requires-Dist: plotly (>=5.14.0) ; extra == "all"
+Requires-Dist: plotly (>=5.14.0) ; extra == "viz"
+Requires-Dist: pre-commit (>=4.5.1) ; extra == "all"
+Requires-Dist: pre-commit (>=4.5.1) ; extra == "dev"
+Requires-Dist: pylint (>=4.0.5) ; extra == "all"
+Requires-Dist: pylint (>=4.0.5) ; extra == "dev"
+Requires-Dist: pytest (>=8.0.0) ; extra == "all"
+Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
+Requires-Dist: pytest-cov (>=5.0.0) ; extra == "all"
+Requires-Dist: pytest-cov (>=5.0.0) ; extra == "dev"
+Requires-Dist: pyvis (>=0.3.2) ; extra == "all"
+Requires-Dist: pyvis (>=0.3.2) ; extra == "viz"
+Requires-Dist: pyvista[jupyter] (>=0.44.0) ; extra == "all"
+Requires-Dist: pyvista[jupyter] (>=0.44.0) ; extra == "viz3d"
+Requires-Dist: pyvistaqt (>=0.11.0) ; extra == "all"
+Requires-Dist: pyvistaqt (>=0.11.0) ; extra == "viz3d"
+Requires-Dist: rich (>=14.3.3,<15)
+Requires-Dist: ruff (>=0.4.0) ; extra == "all"
+Requires-Dist: ruff (>=0.4.0) ; extra == "dev"
+Requires-Dist: safetensors (>=0.5.0)
+Requires-Dist: sentence-transformers (>=5.4.1)
+Requires-Dist: streamlit (>=1.35.0) ; extra == "all"
+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)
+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
+
+
+[![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.16.0-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)
+
+---
+
+## 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.
+
+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
+
+> "Replaces hours of manual exploration with a single call. The most valuable tool in the suite."
+> — Claude Opus 4, on `analyze_repo()`
+
+> "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)
+
+> "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
+
+> "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
+
+---
+
+## Quick Start
+
+Run the one-line installer from within the repo you want to index:
+
+```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
+
+After the script completes, restart your AI agent to activate the MCP server.
+
+```bash
+# Preview without making changes
+curl -fsSL .../install-skill.sh | bash -s -- --dry-run
+
+# Claude Code and GitHub Copilot only
+curl -fsSL .../install-skill.sh | bash -s -- --providers claude,copilot
+```
+
+→ **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
+
+---
+
+## Usage
+
+```bash
+# Build the knowledge graph
+pycodekg build --repo /path/to/your/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/your/repo
+
+# Launch the interactive web app
+pycodekg viz
+
+# Start the MCP server
+pycodekg mcp --repo /path/to/your/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
+
+```python
+from pycode_kg import PyCodeKG
+
+kg = PyCodeKG(repo_root="/path/to/repo")
+kg.build(wipe=True)
+
+result = kg.query("database connection setup", k=8, hop=1)
+for node in result.nodes:
+    print(node["id"], node["name"])
+
+pack = kg.pack("authentication flow")
+pack.save("context.md")
+```
+
+---
+
+## Architecture
+
+<p align="center">
+  <img src="assets/codeKG_arch_square-web.jpg" alt="PyCodeKG architecture workflow" width="600"/>
+</p>
+
+```
+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
+```
+
+The five design principles:
+
+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.
+
+→ **Full architecture documentation:** [docs/Architecture.md](docs/Architecture.md)
+
+---
+
+## Contribution Checklist
+
+When changing MCP tools in `src/pycode_kg/mcp_server.py` (signature, params, defaults, or behavior), update all three in the same commit:
+
+- 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
+
+---
+
+## 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.15.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.PLACEHOLDER
+
+**BibTeX**
+
+```bibtex
+@software{suchanek_pycode_kg,
+  author    = {Suchanek, Eric G.},
+  title     = {{PyCodeKG}: Semantic Knowledge Graph for Python Codebases},
+  version   = {0.15.0},
+  year      = {2026},
+  publisher = {Flux-Frontiers},
+  url       = {https://github.com/Flux-Frontiers/pycode_kg},
+  doi       = {10.5281/zenodo.PLACEHOLDER},
+}
+```
+
+---
+
+## License
+
+[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license) — see [LICENSE](LICENSE).
+