Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions codewiki/cli/adapters/doc_generator.py
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,9 @@ async def _run_backend_generation(self, backend_config: BackendConfig):
validate_module_file_coverage(module_tree, components)
file_manager.save_json(module_tree, first_module_tree_path)
file_manager.save_json(module_tree, module_tree_path)
from codewiki.src.be.cluster_batch_cache import delete_clustering_batch_cache

delete_clustering_batch_cache(working_dir)

self.job.module_count = len(module_tree)

Expand Down
271 changes: 271 additions & 0 deletions codewiki/src/be/cluster_batch_cache.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,271 @@
"""Disk cache for per-batch LLM clustering partial module trees."""

from __future__ import annotations

import hashlib
import json
import logging
import os
import tempfile
from copy import deepcopy
from typing import Any

from codewiki.src.config import CLUSTERING_BATCH_CACHE_FILENAME, Config
from codewiki.src.utils import file_manager

logger = logging.getLogger(__name__)

CACHE_VERSION = 4


def clustering_cache_scope(module_path: list[str]) -> str:
"""Stable scope id for one ``cluster_modules`` invocation."""
if not module_path:
return "__root__"
return "/".join(module_path)


def clustering_request_fingerprint(config: Config, prompt: str) -> str:
"""Identify the rendered request and configured routing without persisting secrets."""
routing = {
name: getattr(config, name, None)
for name in (
"provider",
"cluster_model",
"main_model",
"llm_base_url",
"azure_deployment",
"api_version",
"aws_region",
"google_project",
"google_location",
"max_tokens",
)
}
if routing["provider"] == "google-vertex":
routing["google_project"] = routing["google_project"] or os.getenv(
"GOOGLE_CLOUD_PROJECT", ""
)
routing["google_location"] = (
routing["google_location"] or os.getenv("GOOGLE_CLOUD_LOCATION") or "global"
)
context = {
"repo": os.path.realpath(config.repo_path),
"routing": routing,
"prompt": prompt,
}
canonical = json.dumps(context, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()


def batch_entry_key(
scope: str, batch_index: int, node_ids: list[str], request_fingerprint: str
) -> str:
"""Scope, batch index, component set, and exact request identity."""
canonical = json.dumps(sorted(node_ids), ensure_ascii=False, separators=(",", ":"))
digest = hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:16]
return f"{scope}|{batch_index}|{digest}|{request_fingerprint}"


def clustering_batch_cache_path(docs_dir: str) -> str:
return os.path.join(os.path.abspath(docs_dir), "temp", CLUSTERING_BATCH_CACHE_FILENAME)


def delete_clustering_batch_cache(docs_dir: str, *, scopes: list[str] | None = None) -> None:
"""Remove committed scopes and descendants, or the whole cache after a full build."""
if not docs_dir:
return
if scopes is not None:
if scopes:
ClusterBatchCache(docs_dir).delete_scopes(scopes)
return
_delete_cache_file(clustering_batch_cache_path(docs_dir))


def _delete_cache_file(path: str) -> None:
try:
os.remove(path)
except FileNotFoundError:
return
except OSError as exc:
logger.warning("Could not remove clustering batch cache at %s: %s", path, exc)
return
logger.info("Removed clustering batch cache at %s", path)


def _valid_entry(entry: Any) -> bool:
if not isinstance(entry, dict):
return False
ids = entry.get("node_ids")
partial = entry.get("partial_tree")
return (
isinstance(entry.get("scope"), str)
and isinstance(entry.get("request_fingerprint"), str)
and bool(entry["request_fingerprint"])
and isinstance(entry.get("batch_index"), int)
and not isinstance(entry["batch_index"], bool)
and entry["batch_index"] > 0
and isinstance(ids, list)
and all(isinstance(cid, str) for cid in ids)
and isinstance(partial, dict)
and bool(partial)
and all(
isinstance(name, str)
and isinstance(info, dict)
and isinstance(info.get("path", ""), str)
and isinstance(info.get("components"), list)
and all(isinstance(cid, str) and cid in ids for cid in info["components"])
for name, info in partial.items()
)
)


class ClusterBatchCache:
"""Read/write partial clustering results keyed by scope, batch index, and node set."""

def __init__(self, docs_dir: str, *, enabled: bool = True) -> None:
self._enabled = enabled and bool(docs_dir)
self._path = clustering_batch_cache_path(docs_dir) if self._enabled else ""
self._data: dict[str, Any] = {"version": CACHE_VERSION, "entries": {}}
if self._enabled:
self._load()

def _load(self) -> None:
try:
raw = file_manager.load_json(self._path)
except (OSError, ValueError, UnicodeError) as exc:
logger.warning("Ignoring unreadable clustering batch cache at %s: %s", self._path, exc)
return
if not isinstance(raw, dict) or raw.get("version") != CACHE_VERSION:
return
entries = raw.get("entries")
if isinstance(entries, dict):
entries = {key: entry for key, entry in entries.items() if _valid_entry(entry)}
self._data = {"version": CACHE_VERSION, "entries": entries}
logger.info(
"Loaded clustering batch cache: %d entries from %s",
len(entries),
self._path,
)

def _save(self) -> bool:
"""Publish a complete checkpoint while keeping the previous one on interruption."""
temporary_path = None
try:
directory = os.path.dirname(self._path)
file_manager.ensure_directory(directory)
with tempfile.NamedTemporaryFile(
mode="w", encoding="utf-8", dir=directory, prefix=".clustering-cache-", delete=False
) as stream:
temporary_path = stream.name
json.dump(self._data, stream, indent=4, ensure_ascii=False)
stream.flush()
os.fsync(stream.fileno())
os.replace(temporary_path, self._path)
return True
except OSError as exc:
logger.warning("Could not save clustering batch cache at %s: %s", self._path, exc)
return False
finally:
if temporary_path is not None:
try:
os.remove(temporary_path)
except FileNotFoundError:
pass
except OSError as exc:
logger.warning("Could not remove temporary clustering cache: %s", exc)

def entry_count(self) -> int:
entries = self._data.get("entries")
return len(entries) if isinstance(entries, dict) else 0

def scope_entry_count(self, scope: str) -> int:
entries = self._data.get("entries")
if not isinstance(entries, dict):
return 0
return sum(1 for entry in entries.values() if entry.get("scope") == scope)

def delete_scopes(self, scopes: list[str]) -> None:
"""Keep checkpoints for failed or unrelated subtrees available for retry."""
if not self._enabled or not scopes:
return
selected = set(scopes)
prefixes = tuple(scope + "/" for scope in selected)
entries = self._data["entries"]
remaining = {
key: entry
for key, entry in entries.items()
if entry["scope"] not in selected and not entry["scope"].startswith(prefixes)
}
if len(remaining) == len(entries):
return
self._data["entries"] = remaining
if remaining:
self._save()
else:
_delete_cache_file(self._path)

def lookup(
self, scope: str, batch_index: int, node_ids: list[str], *, request_fingerprint: str
) -> dict[str, Any] | None:
if not self._enabled:
return None
key = batch_entry_key(scope, batch_index, node_ids, request_fingerprint)
entry = self._data["entries"].get(key)
if not _valid_entry(entry):
return None
stored_ids = entry.get("node_ids")
if (
stored_ids != sorted(node_ids)
or entry["scope"] != scope
or entry["batch_index"] != batch_index
or entry["request_fingerprint"] != request_fingerprint
):
return None
partial = entry.get("partial_tree")
if not isinstance(partial, dict) or not partial:
return None
logger.info(
"Using cached clustering result for scope %s batch %d (%d components).",
scope,
batch_index,
len(node_ids),
)
return deepcopy(partial)

def store(
self,
scope: str,
batch_index: int,
node_ids: list[str],
partial_tree: dict[str, Any],
*,
request_fingerprint: str,
) -> None:
if not self._enabled or not partial_tree:
return
key = batch_entry_key(scope, batch_index, node_ids, request_fingerprint)
entry = {
"scope": scope,
"batch_index": batch_index,
"node_ids": sorted(node_ids),
"request_fingerprint": request_fingerprint,
"partial_tree": deepcopy(partial_tree),
}
if not _valid_entry(entry):
return
self._data["entries"][key] = entry
if not self._save():
return
module_names = list(partial_tree.keys())
logger.info(
"Stored clustering batch cache for scope %s batch %d (%d components, %d modules: %s); "
"%d total entries at %s",
scope,
batch_index,
len(node_ids),
len(module_names),
", ".join(module_names[:5]) + ("..." if len(module_names) > 5 else ""),
self.entry_count(),
self._path,
)
59 changes: 55 additions & 4 deletions codewiki/src/be/cluster_modules.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,11 @@
from collections.abc import Callable
from typing import Any

from codewiki.src.be.cluster_batch_cache import (
ClusterBatchCache,
clustering_cache_scope,
clustering_request_fingerprint,
)
from codewiki.src.be.dependency_analyzer.models.core import Node
from codewiki.src.be.llm_services import call_llm
from codewiki.src.be.module_naming import resolve_unique_name, sanitize_module_name
Expand Down Expand Up @@ -170,16 +175,19 @@ def _cluster_via_llm(
current_module_name: str | None,
module_label: str,
completer: Completer | None,
*,
prompt: str | None = None,
) -> dict[str, Any]:
"""Run one clustering LLM call over these nodes.

Returns {} for any empty, malformed, or non-dict response instead of
raising, so callers can fall back gracefully.
"""
potential_core_components, _ = format_potential_core_components(leaf_nodes, components)
prompt = format_cluster_prompt(
potential_core_components, current_module_tree, current_module_name
)
if prompt is None:
potential_core_components, _ = format_potential_core_components(leaf_nodes, components)
prompt = format_cluster_prompt(
potential_core_components, current_module_tree, current_module_name
)
if completer is not None:
response = completer(prompt)
else:
Expand Down Expand Up @@ -428,9 +436,37 @@ def cluster_modules(
module_label,
len(batches),
)
batch_cache: ClusterBatchCache | None = None
cache_scope = clustering_cache_scope(current_module_path)
if getattr(config, "cluster_batch_cache", True) and config.docs_dir:
batch_cache = ClusterBatchCache(config.docs_dir)
module_tree = {}
cache_hits = 0
if batch_cache is not None:
logger.info(
"Clustering batch cache for %r: %d on-disk entries (%d for this scope), %d batches to run.",
cache_scope,
batch_cache.entry_count(),
batch_cache.scope_entry_count(cache_scope),
len(batches),
)
for i, batch in enumerate(batches, 1):
batch_label = f"{module_label} (batch {i}/{len(batches)})"
potential_core_components, _ = format_potential_core_components(batch, components)
prompt = format_cluster_prompt(
potential_core_components, current_module_tree, current_module_name
)
request_fingerprint = (
clustering_request_fingerprint(config, prompt) if batch_cache is not None else ""
)
if batch_cache is not None:
cached = batch_cache.lookup(
cache_scope, i, batch, request_fingerprint=request_fingerprint
)
if cached is not None:
cache_hits += 1
_merge_module_trees(module_tree, cached)
continue
# Each batch gets the *unmodified* current_module_tree: passing the
# accumulating merge would flip format_cluster_prompt into its
# module-level variant mid-partition.
Expand All @@ -442,7 +478,14 @@ def cluster_modules(
current_module_name,
batch_label,
completer,
prompt=prompt,
)
# Only validated LLM responses are resumable. A structural fallback
# keeps this pass usable but must be retried after a later failure.
if batch_cache is not None and partial:
batch_cache.store(
cache_scope, i, batch, partial, request_fingerprint=request_fingerprint
)
if not partial:
name = _batch_fallback_name(batch, components, module_tree)
partial = {
Expand All @@ -460,6 +503,14 @@ def cluster_modules(
name,
)
_merge_module_trees(module_tree, partial)
if batch_cache is not None:
logger.info(
"Clustering batch cache for %r: %d/%d batches from cache, %d LLM batch call(s) this pass.",
cache_scope,
cache_hits,
len(batches),
len(batches) - cache_hits,
)

module_tree = normalize_module_partition(module_tree, candidates, components)
if len(module_tree) <= 1:
Expand Down
3 changes: 3 additions & 0 deletions codewiki/src/be/documentation_generator.py
Original file line number Diff line number Diff line change
Expand Up @@ -545,6 +545,9 @@ async def run(self) -> None:
validate_module_file_coverage(module_tree, components)
file_manager.save_json(module_tree, first_module_tree_path)
file_manager.save_json(module_tree, module_tree_path)
from codewiki.src.be.cluster_batch_cache import delete_clustering_batch_cache

delete_clustering_batch_cache(working_dir)

if len(module_tree) == 0:
logger.info(
Expand Down
Loading
Loading