pycode-kg 0.16.0__py3-none-any.whl

pycode_kg/analysis/framework_detector.py

@@ -0,0 +1,103 @@
+"""
+Framework Detector for PyCodeKG.
+Identifies repo-defining abstractions using centrality and cross-module signals.
+"""
+
+import sqlite3
+
+# Short method names that are structurally high fan-in but architecturally trivial.
+# Excluded from framework-node ranking so hubs surface over lifecycle boilerplate.
+_BOILERPLATE_NAMES: frozenset[str] = frozenset(
+    {
+        "close",
+        "__init__",
+        "__exit__",
+        "__enter__",
+        "__del__",
+        "__repr__",
+        "__str__",
+        "__len__",
+        "__iter__",
+        "__next__",
+        "__contains__",
+        "__bool__",
+        "__hash__",
+        "__eq__",
+        "__ne__",
+        "__lt__",
+        "__gt__",
+        "__le__",
+        "__ge__",
+        "__call__",
+    }
+)
+
+
+def detect_framework_nodes(limit=25, db_path="pycodekg.sqlite"):
+    """
+    Detect framework-like nodes using SIR and module connectivity.
+
+    Combines Structural Importance Ranking (SIR — importance within the graph)
+    with module connectivity (interaction complexity) to identify modules that are
+    both architecturally central AND highly connected to other modules.
+
+    Framework score = 0.6 × normalized SIR + 0.4 × normalized connectivity.
+    High-scoring modules are critical hubs: important AND complex.
+
+    Lifecycle / protocol boilerplate (``close``, ``__init__``, ``__exit__``, etc.)
+    is excluded so the ranking surfaces meaningful orchestrators rather than
+    the most-called teardown methods.
+
+    :param limit: Number of top framework nodes to return (default 25).
+    :param db_path: Path to SQLite database (default "pycodekg.sqlite").
+    :return: List of (node_id, framework_score, label) tuples, sorted by score descending.
+    """
+    with sqlite3.connect(db_path) as con:
+        # Get SIR (structural importance) and connectivity (interaction complexity) scores
+        sir = dict(
+            con.execute(
+                "SELECT node_id, score FROM centrality_scores WHERE metric = 'sir_pagerank'"
+            )
+        )
+        connectivity = dict(
+            con.execute(
+                "SELECT node_id, score FROM centrality_scores WHERE metric = 'module_connectivity'"
+            )
+        )
+        # Get module names (for labelling)
+        names = dict(con.execute("SELECT id, name FROM nodes WHERE kind = 'module'"))
+        # Fetch qualnames for boilerplate filtering across all node kinds
+        qualnames: dict[str, str] = dict(
+            con.execute("SELECT id, COALESCE(qualname, name) FROM nodes")
+        )
+
+    def _is_boilerplate(node_id: str) -> bool:
+        qn = qualnames.get(node_id, node_id)
+        short = qn.split(".")[-1] if "." in qn else qn
+        return short in _BOILERPLATE_NAMES
+
+    # Normalize scores to [0, 1]
+    def norm(d: dict) -> dict:
+        if not d:
+            return {}
+        vals = list(d.values())
+        mn, mx = min(vals), max(vals)
+        return {k: (v - mn) / (mx - mn) if mx > mn else 0.0 for k, v in d.items()}
+
+    nsir = norm(sir)
+    nconnectivity = norm(connectivity)
+
+    # Framework score: weighted sum (SIR 60% — importance, connectivity 40% — coupling)
+    # Skip boilerplate methods that score high purely due to lifecycle call frequency.
+    framework = {}
+    for k in set(nsir) | set(nconnectivity):
+        if _is_boilerplate(k):
+            continue
+        framework[k] = 0.6 * nsir.get(k, 0.0) + 0.4 * nconnectivity.get(k, 0.0)
+
+    ranked = sorted(framework.items(), key=lambda x: x[1], reverse=True)
+    result = []
+    for node_id, score in ranked[:limit]:
+        label = names.get(node_id, node_id)
+        result.append((node_id, score, label))
+    return result

pycode_kg/analysis/hybrid_rank.py

@@ -0,0 +1,53 @@
+"""
+Hybrid Search Ranking for PyCodeKG.
+Combines semantic relevance with structural importance (SIR).
+"""
+
+import math
+import sqlite3
+
+
+def get_sir_scores(metric="sir_pagerank", db_path="pycodekg.sqlite"):
+    """Fetch SIR centrality scores from the database."""
+    with sqlite3.connect(db_path) as con:
+        rows = con.execute(
+            "SELECT node_id, score FROM centrality_scores WHERE metric = ?", (metric,)
+        ).fetchall()
+    scores = {node_id: score for node_id, score in rows}
+    if not scores:
+        return {}
+    max_score = max(scores.values())
+    min_score = min(scores.values())
+
+    # Normalize to [0,1]
+    def norm(s):
+        return (s - min_score) / (max_score - min_score) if max_score > min_score else 0.0
+
+    return {k: norm(v) for k, v in scores.items()}
+
+
+def rerank_hybrid(
+    results, centrality_metric="sir_pagerank", lambda_weight=0.15, db_path="pycodekg.sqlite"
+):
+    """
+    Rerank search results using hybrid score.
+    :param results: List of dicts with 'node_id' and 'semantic_score'
+    :param centrality_metric: Centrality metric to use (default 'sir_pagerank')
+    :param lambda_weight: Weight for structural term (default 0.15)
+    :param db_path: Path to SQLite database
+    :return: List of dicts with hybrid scores
+    """
+    sir_scores = get_sir_scores(centrality_metric, db_path)
+    reranked = []
+    for r in results:
+        node_id = r.get("node_id")
+        sem = r.get("semantic_score", 0.0)
+        struct = sir_scores.get(node_id, 0.0)
+        # Hybrid score: semantic + lambda * log(1 + struct)
+        hybrid = sem + lambda_weight * math.log(1 + struct)
+        out = dict(r)
+        out["structural_score"] = struct
+        out["hybrid_score"] = hybrid
+        reranked.append(out)
+    reranked.sort(key=lambda x: x["hybrid_score"], reverse=True)
+    return reranked