kgzip 0.1.0__py3-none-any.whl

kgzip/__init__.py

@@ -0,0 +1,7 @@
+from kgzip import compat  # noqa: F401 — applies nest_asyncio if needed
+from kgzip._version import __version__
+from kgzip.exceptions import KGZipError
+from kgzip.serialize import to_compact, to_triples
+from kgzip.store import KGZipStore
+
+__all__ = ["KGZipStore", "KGZipError", "to_triples", "to_compact", "__version__"]

kgzip/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version."""
+
+__version__ = "0.1.0"

kgzip/benchmark/__init__.py

@@ -0,0 +1,5 @@
+from kgzip.benchmark.medical_kg import generate_medical_kg
+from kgzip.benchmark.harness import time_query
+from kgzip.benchmark.comparison import run_benchmark
+
+__all__ = ["generate_medical_kg", "time_query", "run_benchmark"]

kgzip/benchmark/comparison.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import tempfile
+import time
+from collections import deque
+from typing import List
+
+import networkx as nx
+
+from kgzip.benchmark.harness import time_query
+from kgzip.models import (
+    BenchmarkReport,
+    DecisionConfig,
+    KGZipConfig,
+    StorageConfig,
+)
+from kgzip.store import KGZipStore
+
+logger = logging.getLogger(__name__)
+
+# Number of timed runs per method (kept small to keep tests fast)
+_BENCH_RUNS = 5
+
+
+def _bfs_subgraph(G: nx.DiGraph, seed_nodes: List[str], depth: int) -> set:
+    visited: set = set()
+    queue: deque = deque()
+    seen: set = set()
+    for n in seed_nodes:
+        if n in G:
+            queue.append((n, 0))
+            seen.add(n)
+    while queue:
+        node, d = queue.popleft()
+        visited.add(node)
+        if d < depth:
+            for nbr in G.successors(node):
+                if nbr not in seen:
+                    seen.add(nbr)
+                    queue.append((nbr, d + 1))
+    return visited
+
+
+def run_benchmark(
+    graph: nx.DiGraph,
+    query_node_ids: List[str],
+    depth: int = 2,
+) -> BenchmarkReport:
+    """Compare standard (full-graph-load) traversal against KGZip capsule query.
+
+    Standard baseline: serialize full graph as JSON to disk; each timed run
+    loads the JSON from disk, reconstructs the graph, then runs BFS. This
+    mirrors how a naive graph store would answer queries — reading all data for
+    every access.
+
+    KGZip: compresses the graph into parallel-decodable capsules; each timed
+    run decodes only the capsules relevant to the query.
+
+    Returns BenchmarkReport with timing statistics and size comparison.
+    """
+    baseline_dir = tempfile.mkdtemp(prefix="kgzip_bench_std_")
+    kgzip_dir = tempfile.mkdtemp(prefix="kgzip_bench_kgz_")
+
+    try:
+        # --- Standard baseline setup ---
+        graph_data = nx.node_link_data(graph)
+        baseline_path = os.path.join(baseline_dir, "graph.json")
+        with open(baseline_path, "w", encoding="utf-8") as f:
+            json.dump(graph_data, f)
+        original_size_estimate_bytes = os.path.getsize(baseline_path)
+
+        def _standard_run() -> set:
+            with open(baseline_path, encoding="utf-8") as f:
+                data = json.load(f)
+            G = nx.node_link_graph(data)
+            return _bfs_subgraph(G, query_node_ids, depth)
+
+        # warm-up (avoids first-call cold-start bias)
+        _standard_run()
+        standard_stats = time_query(_standard_run, runs=_BENCH_RUNS)
+
+        # --- KGZip setup ---
+        # Small capsule cap ensures multiple capsules so queries load a fraction.
+        kgzip_config = KGZipConfig(
+            decision=DecisionConfig(
+                max_capsule_nodes=100,
+                min_capsule_nodes=5,
+                random_seed=42,
+            ),
+            storage=StorageConfig(
+                base_path=kgzip_dir,
+                compression="zstd",
+                compression_level=3,
+            ),
+        )
+        store = KGZipStore(kgzip_dir, kgzip_config)
+
+        t0 = time.monotonic()
+        store_ref = store.compress(graph)
+        compress_time_ms = (time.monotonic() - t0) * 1000.0
+
+        # warm-up
+        store.query(query_node_ids, depth=depth)
+
+        kgzip_stats = time_query(
+            lambda: store.query(query_node_ids, depth=depth),
+            runs=_BENCH_RUNS,
+        )
+
+        speedup_ratio = (
+            standard_stats["mean_ms"] / kgzip_stats["mean_ms"]
+            if kgzip_stats["mean_ms"] > 0.0
+            else 0.0
+        )
+
+        report = BenchmarkReport(
+            compress_time_ms=compress_time_ms,
+            standard_mean_ms=standard_stats["mean_ms"],
+            kgzip_mean_ms=kgzip_stats["mean_ms"],
+            speedup_ratio=speedup_ratio,
+            capsule_count=store_ref.capsule_count,
+            store_size_bytes=store_ref.total_bytes,
+            original_size_estimate_bytes=original_size_estimate_bytes,
+        )
+
+        _print_summary(report, graph)
+        return report
+
+    finally:
+        shutil.rmtree(baseline_dir, ignore_errors=True)
+        shutil.rmtree(kgzip_dir, ignore_errors=True)
+
+
+def _print_summary(report: BenchmarkReport, graph: nx.DiGraph) -> None:
+    print(
+        f"\n{'='*60}\n"
+        f"KGZip Benchmark Results\n"
+        f"{'='*60}\n"
+        f"Graph:          {graph.number_of_nodes()} nodes, {graph.number_of_edges()} edges\n"
+        f"Capsules:       {report.capsule_count}\n"
+        f"Compress time:  {report.compress_time_ms:.1f} ms\n"
+        f"\nQuery latency (mean over {_BENCH_RUNS} runs):\n"
+        f"  Standard BFS: {report.standard_mean_ms:.2f} ms\n"
+        f"  KGZip:        {report.kgzip_mean_ms:.2f} ms\n"
+        f"  Speedup:      {report.speedup_ratio:.2f}x\n"
+        f"\nStorage:\n"
+        f"  Original est: {report.original_size_estimate_bytes:,} bytes\n"
+        f"  KGZip store:  {report.store_size_bytes:,} bytes\n"
+        f"  Reduction:    {100*(1 - report.store_size_bytes/max(report.original_size_estimate_bytes,1)):.1f}%\n"
+        f"{'='*60}\n"
+    )

kgzip/benchmark/harness.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import statistics
+import time
+from typing import Any, Callable, Dict
+
+
+def time_query(fn: Callable, *args: Any, runs: int = 10) -> Dict[str, float]:
+    """Time fn(*args) over N runs and return wall-time statistics in milliseconds."""
+    times: list = []
+    for _ in range(runs):
+        t0 = time.monotonic()
+        fn(*args)
+        times.append((time.monotonic() - t0) * 1000.0)
+
+    return {
+        "mean_ms": statistics.mean(times),
+        "median_ms": statistics.median(times),
+        "min_ms": min(times),
+        "max_ms": max(times),
+        "std_ms": statistics.stdev(times) if len(times) > 1 else 0.0,
+    }

kgzip/benchmark/medical_kg.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import random
+
+import networkx as nx
+
+
+def generate_medical_kg(
+    n_drugs: int = 50,
+    n_diseases: int = 100,
+    n_genes: int = 200,
+    n_proteins: int = 150,
+    seed: int = 42,
+) -> nx.DiGraph:
+    """Generate a synthetic medical knowledge graph with realistic community structure.
+
+    Node types and approximate counts (defaults → ~500 nodes, ~1500 edges):
+      Drug --treats--> Disease
+      Disease --associated_with--> Gene
+      Gene --encodes--> Protein
+      Drug --targets--> Protein
+      Disease --comorbid_with--> Disease
+    """
+    rng = random.Random(seed)
+    G = nx.DiGraph()
+
+    drugs = [f"Drug_{i}" for i in range(n_drugs)]
+    diseases = [f"Disease_{i}" for i in range(n_diseases)]
+    genes = [f"Gene_{i}" for i in range(n_genes)]
+    proteins = [f"Protein_{i}" for i in range(n_proteins)]
+
+    for node in drugs:
+        G.add_node(node, node_type="drug", name=node)
+    for node in diseases:
+        G.add_node(node, node_type="disease", name=node)
+    for node in genes:
+        G.add_node(node, node_type="gene", name=node)
+    for node in proteins:
+        G.add_node(node, node_type="protein", name=node)
+
+    # Drug --treats--> Disease
+    for drug in drugs:
+        count = rng.randint(3, 6)
+        for disease in rng.sample(diseases, min(count, len(diseases))):
+            G.add_edge(drug, disease, relation="treats")
+
+    # Disease --associated_with--> Gene
+    for disease in diseases:
+        count = rng.randint(4, 8)
+        for gene in rng.sample(genes, min(count, len(genes))):
+            G.add_edge(disease, gene, relation="associated_with")
+
+    # Gene --encodes--> Protein
+    for gene in genes:
+        count = rng.randint(1, 3)
+        for protein in rng.sample(proteins, min(count, len(proteins))):
+            G.add_edge(gene, protein, relation="encodes")
+
+    # Drug --targets--> Protein
+    for drug in drugs:
+        count = rng.randint(2, 4)
+        for protein in rng.sample(proteins, min(count, len(proteins))):
+            G.add_edge(drug, protein, relation="targets")
+
+    # Disease --comorbid_with--> Disease (sparse)
+    comorbid_count = int(n_diseases * 0.5)
+    sampled = rng.sample(diseases, min(comorbid_count * 2, len(diseases)))
+    for i in range(0, len(sampled) - 1, 2):
+        G.add_edge(sampled[i], sampled[i + 1], relation="comorbid_with")
+
+    return G

kgzip/benchmark/quality.py

@@ -0,0 +1,226 @@
+"""Query-quality evaluation harness for KGZip.
+
+KGZip retrieves at *capsule* granularity: a depth-k query loads the seed's capsule
+(plus neighbour capsules for deeper queries) and returns their full contents. That
+is not the same as the exact k-hop neighbourhood of the seed. This harness measures
+how well capsule retrieval approximates the true neighbourhood, across graph sizes.
+
+Metrics (averaged over sampled seeds, per depth):
+  node_recall    = |returned ∩ true| / |true|        (did we get the real neighbourhood?)
+  node_precision = |returned ∩ true| / |returned|     (how much extra did we pull in?)
+  edge_recall / edge_precision  — same, over edge (src,dst,relation) signatures
+  perfect_recall_frac           — fraction of seeds with node_recall == 1.0
+
+A separate full-graph check confirms losslessness: querying every node returns the
+entire original graph (recall == precision == 1.0).
+
+Run directly:
+    python -m kgzip.benchmark.quality                # default scales
+    python -m kgzip.benchmark.quality 100 1000 10000  # custom node counts
+"""
+from __future__ import annotations
+
+import random
+import tempfile
+import time
+from collections import deque
+from typing import Dict, List, Set, Tuple
+
+import networkx as nx
+
+from kgzip.benchmark.medical_kg import generate_medical_kg
+from kgzip.models import DecisionConfig, KGZipConfig, StorageConfig
+from kgzip.store import KGZipStore
+
+DEFAULT_SCALES = [100, 1_000, 10_000, 50_000, 100_000]
+DEFAULT_DEPTHS = [1, 2]
+DEFAULT_N_SEEDS = 20
+
+_BASE_TOTAL = 500  # generate_medical_kg default node total (50+100+200+150)
+
+
+def _scaled_medical_kg(n_nodes: int, seed: int = 42) -> nx.DiGraph:
+    """Generate a medical KG scaled to approximately *n_nodes* nodes."""
+    factor = n_nodes / _BASE_TOTAL
+    return generate_medical_kg(
+        n_drugs=max(1, round(50 * factor)),
+        n_diseases=max(1, round(100 * factor)),
+        n_genes=max(1, round(200 * factor)),
+        n_proteins=max(1, round(150 * factor)),
+        seed=seed,
+    )
+
+
+def _true_neighbourhood(
+    G: nx.DiGraph, seed: str, depth: int
+) -> Tuple[Set[str], Set[Tuple[str, str, str]]]:
+    """Undirected k-hop neighbourhood of *seed*: node set and edge signature set."""
+    visited: Set[str] = {seed}
+    frontier = {seed}
+    for _ in range(depth):
+        nxt: Set[str] = set()
+        for n in frontier:
+            nxt.update(G.predecessors(n))
+            nxt.update(G.successors(n))
+        nxt -= visited
+        visited |= nxt
+        frontier = nxt
+        if not frontier:
+            break
+    edges: Set[Tuple[str, str, str]] = set()
+    for u, v, data in G.edges(data=True):
+        if u in visited and v in visited:
+            edges.add((u, v, data.get("relation", "related_to")))
+    return visited, edges
+
+
+def _safe_div(a: float, b: float) -> float:
+    return a / b if b else 1.0
+
+
+def evaluate_scale(
+    n_nodes: int,
+    depths: List[int] = None,
+    n_seeds: int = DEFAULT_N_SEEDS,
+    seed: int = 42,
+) -> Dict:
+    """Compress a scaled synthetic KG and measure query quality at each depth."""
+    depths = depths or DEFAULT_DEPTHS
+    rng = random.Random(seed)
+
+    G = _scaled_medical_kg(n_nodes, seed=seed)
+    actual_nodes = G.number_of_nodes()
+    actual_edges = G.number_of_edges()
+
+    store_dir = tempfile.mkdtemp(prefix="kgzip_quality_")
+    config = KGZipConfig(
+        decision=DecisionConfig(random_seed=seed),
+        storage=StorageConfig(base_path=store_dir, compression="zstd", compression_level=3),
+    )
+    store = KGZipStore(store_dir, config)
+
+    t0 = time.monotonic()
+    ref = store.compress(G)
+    compress_ms = (time.monotonic() - t0) * 1000.0
+
+    all_ids = [str(n) for n in G.nodes()]
+    seeds = rng.sample(all_ids, min(n_seeds, len(all_ids)))
+
+    per_depth: Dict[int, Dict[str, float]] = {}
+    for depth in depths:
+        nr = np = er = ep = 0.0
+        perfect = 0
+        lat_ms = 0.0
+        for s in seeds:
+            t = time.monotonic()
+            result = store.query([s], depth=depth)
+            lat_ms += (time.monotonic() - t) * 1000.0
+
+            ret_nodes = {n.id for n in result.subgraph.nodes}
+            ret_edges = {(e.src, e.dst, e.relation) for e in result.subgraph.edges}
+            true_nodes, true_edges = _true_neighbourhood(G, s, depth)
+
+            inter_n = len(ret_nodes & true_nodes)
+            inter_e = len(ret_edges & true_edges)
+            node_recall = _safe_div(inter_n, len(true_nodes))
+            nr += node_recall
+            np += _safe_div(inter_n, len(ret_nodes))
+            er += _safe_div(inter_e, len(true_edges))
+            ep += _safe_div(inter_e, len(ret_edges))
+            if node_recall >= 0.999:
+                perfect += 1
+
+        k = len(seeds)
+        per_depth[depth] = {
+            "node_recall": nr / k,
+            "node_precision": np / k,
+            "edge_recall": er / k,
+            "edge_precision": ep / k,
+            "perfect_recall_frac": perfect / k,
+            "mean_latency_ms": lat_ms / k,
+        }
+
+    # Losslessness check: query every node, expect the whole graph back. This is only
+    # meaningful when the store fits under the per-query capsule cap (50); above that a
+    # single query is intentionally capped, so we mark it n/a rather than a false fail.
+    from kgzip.query.interface import _MAX_CAPSULES_PER_QUERY
+
+    if ref.capsule_count <= _MAX_CAPSULES_PER_QUERY:
+        full = store.query(all_ids, depth=1)
+        full_nodes = {n.id for n in full.subgraph.nodes}
+        full_edges = {(e.src, e.dst, e.relation) for e in full.subgraph.edges}
+        orig_edges = {(str(u), str(v), d.get("relation", "related_to")) for u, v, d in G.edges(data=True)}
+        lossless = (full_nodes == set(all_ids)) and (full_edges == orig_edges)
+    else:
+        lossless = None  # n/a: exceeds the 50-capsule per-query cap
+
+    return {
+        "requested_nodes": n_nodes,
+        "actual_nodes": actual_nodes,
+        "actual_edges": actual_edges,
+        "capsule_count": ref.capsule_count,
+        "store_bytes": ref.total_bytes,
+        "compress_ms": compress_ms,
+        "per_depth": per_depth,
+        "lossless_full_query": lossless,
+    }
+
+
+def run_quality_eval(
+    scales: List[int] = None,
+    depths: List[int] = None,
+    n_seeds: int = DEFAULT_N_SEEDS,
+    seed: int = 42,
+) -> List[Dict]:
+    scales = scales or DEFAULT_SCALES
+    depths = depths or DEFAULT_DEPTHS
+    reports = []
+    for n in scales:
+        print(f"\n[quality] evaluating ~{n:,} nodes ...", flush=True)
+        rep = evaluate_scale(n, depths=depths, n_seeds=n_seeds, seed=seed)
+        reports.append(rep)
+        _print_scale(rep)
+    _print_summary(reports, depths)
+    return reports
+
+
+def _print_scale(rep: Dict) -> None:
+    print(
+        f"  nodes={rep['actual_nodes']:,} edges={rep['actual_edges']:,} "
+        f"capsules={rep['capsule_count']} "
+        f"store={rep['store_bytes']:,}B compress={rep['compress_ms']:.0f}ms "
+        f"lossless_full={rep['lossless_full_query']}"
+    )
+    for depth, m in rep["per_depth"].items():
+        print(
+            f"    depth={depth}: "
+            f"node_recall={m['node_recall']:.2f} node_prec={m['node_precision']:.2f} "
+            f"edge_recall={m['edge_recall']:.2f} edge_prec={m['edge_precision']:.2f} "
+            f"perfect_recall={m['perfect_recall_frac']:.0%} "
+            f"lat={m['mean_latency_ms']:.2f}ms"
+        )
+
+
+def _print_summary(reports: List[Dict], depths: List[int]) -> None:
+    print(f"\n{'='*84}\nKGZip query-quality summary\n{'='*84}")
+    header = f"{'nodes':>9} {'caps':>5} {'depth':>5} {'n_rec':>6} {'n_prec':>7} {'e_rec':>6} {'e_prec':>7} {'lat_ms':>7}"
+    print(header)
+    print("-" * len(header))
+    for rep in reports:
+        for depth in depths:
+            m = rep["per_depth"][depth]
+            print(
+                f"{rep['actual_nodes']:>9,} {rep['capsule_count']:>5} {depth:>5} "
+                f"{m['node_recall']:>6.2f} {m['node_precision']:>7.2f} "
+                f"{m['edge_recall']:>6.2f} {m['edge_precision']:>7.2f} {m['mean_latency_ms']:>7.2f}"
+            )
+    all_lossless = all(r["lossless_full_query"] for r in reports)
+    print("-" * len(header))
+    print(f"full-graph query lossless at every scale: {all_lossless}")
+
+
+if __name__ == "__main__":
+    import sys
+
+    args = [int(a) for a in sys.argv[1:]] if len(sys.argv) > 1 else None
+    run_quality_eval(scales=args)

kgzip/compat.py

@@ -0,0 +1,77 @@
+"""asyncio compatibility helpers for KGZip.
+
+KGZip exposes a synchronous public API but decodes capsules with asyncio under the
+hood. This module provides :func:`run_coro`, which drives a coroutine to completion
+from synchronous code in *both* plain scripts and environments that already have a
+running event loop (Jupyter, or being called from inside async code).
+
+It deliberately avoids the deprecated ``asyncio.get_event_loop()`` pattern, which
+raises/ warns on Python 3.10+ when there is no current loop.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+
+logger = logging.getLogger(__name__)
+
+_NEST_APPLIED = False
+
+# A dedicated event loop per thread, reused across calls. Reuse avoids the
+# per-call setup/teardown cost of asyncio.run(); thread-local storage keeps it
+# safe to call query() concurrently from multiple threads (each thread drives
+# its own loop, and a loop is not safe to share across threads).
+_thread_local = threading.local()
+
+
+def _ensure_nest_asyncio() -> None:
+    """Apply nest_asyncio once so a running loop can be re-entered. Idempotent."""
+    global _NEST_APPLIED
+    if _NEST_APPLIED:
+        return
+    try:
+        import nest_asyncio
+
+        nest_asyncio.apply()
+        _NEST_APPLIED = True
+        logger.debug("nest_asyncio applied for re-entrant event loop support")
+    except Exception:  # pragma: no cover - nest_asyncio is a declared dependency
+        # Non-fatal: only matters when called from within a running loop.
+        pass
+
+
+def run_coro(coro):
+    """Run *coro* to completion and return its result, from synchronous code.
+
+    - No running loop (scripts, pytest, normal use): run on a reused per-thread
+      loop. Thread-safe — each thread drives its own loop.
+    - Running loop present (Jupyter, or invoked from async code): apply nest_asyncio
+      once and re-enter the existing loop.
+    """
+    try:
+        running_loop = asyncio.get_running_loop()
+    except RuntimeError:
+        running_loop = None
+
+    if running_loop is not None:
+        _ensure_nest_asyncio()
+        return running_loop.run_until_complete(coro)
+
+    loop = getattr(_thread_local, "loop", None)
+    if loop is None or loop.is_closed():
+        loop = asyncio.new_event_loop()
+        _thread_local.loop = loop
+    return loop.run_until_complete(coro)
+
+
+def _apply_on_import() -> None:
+    """If imported while a loop is already running (e.g. Jupyter), patch it now."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return  # no running loop at import time — nothing to do
+    _ensure_nest_asyncio()
+
+
+_apply_on_import()

kgzip/decision/__init__.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import List, Set
+
+from kgzip.decision.community import detect_communities
+from kgzip.decision.gcs_scorer import estimate_score
+from kgzip.decision.mode_selector import select_mode
+from kgzip.decision.profiler import profile
+from kgzip.decision.spectral import compute_fingerprint
+from kgzip.exceptions import EmptyGraphError
+from kgzip.models import (
+    CapsulePlan,
+    DecisionConfig,
+    DecisionPlan,
+    NormalizedGraph,
+    PlanMeta,
+)
+
+__all__ = [
+    "profile",
+    "detect_communities",
+    "compute_fingerprint",
+    "build_plan",
+]
+
+
+def build_plan(
+    graph: NormalizedGraph, config: DecisionConfig = None
+) -> DecisionPlan:
+    if config is None:
+        config = DecisionConfig()
+
+    if graph.meta.node_count == 0:
+        raise EmptyGraphError("Cannot build plan for empty graph")
+
+    graph_profile = profile(graph)
+    communities: List[Set[str]] = detect_communities(graph, config)
+
+    # Build a reverse lookup: node_id → community index
+    node_to_comm: dict = {}
+    for idx, comm in enumerate(communities):
+        for nid in comm:
+            node_to_comm[nid] = idx
+
+    # Identify boundary nodes and neighbor capsule relationships
+    boundary_sets: List[Set[str]] = [set() for _ in communities]
+    # We'll use indices now; capsule_ids assigned after
+    neighbor_sets: List[Set[int]] = [set() for _ in communities]
+
+    for edge in graph.edges:
+        src_idx = node_to_comm.get(edge.src)
+        dst_idx = node_to_comm.get(edge.dst)
+        if src_idx is not None and dst_idx is not None and src_idx != dst_idx:
+            boundary_sets[src_idx].add(edge.src)
+            boundary_sets[dst_idx].add(edge.dst)
+            neighbor_sets[src_idx].add(dst_idx)
+            neighbor_sets[dst_idx].add(src_idx)
+
+    # Assign capsule UUIDs
+    capsule_ids = [str(uuid.uuid4()) for _ in communities]
+
+    capsules: List[CapsulePlan] = []
+    for idx, comm in enumerate(communities):
+        mode = select_mode(comm, graph, config)
+        fp = compute_fingerprint(comm, graph, config.spectral_k)
+        gcs = estimate_score(comm, graph)
+        neighbor_ids = [capsule_ids[j] for j in neighbor_sets[idx]]
+
+        capsules.append(
+            CapsulePlan(
+                capsule_id=capsule_ids[idx],
+                node_ids=set(comm),
+                boundary_nodes=boundary_sets[idx],
+                encoding_mode=mode,
+                gcs_score=gcs,
+                spectral_fp=fp,
+                neighbor_capsules=neighbor_ids,
+            )
+        )
+
+    # Compute community modularity via Louvain Q
+    try:
+        import community as louvain_community
+        nxg = graph.to_networkx().to_undirected()
+        partition = {nid: idx for idx, comm in enumerate(communities) for nid in comm}
+        modularity = louvain_community.modularity(partition, nxg)
+    except Exception:
+        modularity = -1.0
+
+    mean_gcs = sum(c.gcs_score for c in capsules) / len(capsules) if capsules else 0.0
+
+    plan_meta = PlanMeta(
+        total_capsules=len(capsules),
+        mean_gcs=mean_gcs,
+        community_modularity=modularity,
+        planned_at=datetime.now(timezone.utc).isoformat(),
+    )
+
+    return DecisionPlan(capsules=capsules, plan_meta=plan_meta)