codegraph-engine 2.1.1__py3-none-any.whl

codegraph/resources/__init__.py

@@ -0,0 +1,45 @@
+"""Resource Management, Concurrency Throttling, and Laptop Protection.
+
+Provides:
+- ResourceGovernor: Priority scheduling, cooperative yielding, process memory monitoring
+- ResourcePolicy: Profiles (LIGHT, BALANCED, PERFORMANCE), bounds, and thresholds
+- RequestCoalescer: De-duplicating identical concurrent flights
+- FileChangeDebouncer: Coalescing editor save bursts
+- BoundedMemoryCache: Memory-bounded LRU caches for parse results and graphs
+"""
+from __future__ import annotations
+
+from .cache import (
+    BoundedMemoryCache,
+    get_graph_cache,
+    get_parse_cache,
+)
+from .coalescer import RequestCoalescer, get_global_coalescer
+from .debouncer import FileChangeDebouncer
+from .governor import ResourceGovernor, get_global_governor, get_process_memory_mb
+from .policy import (
+    ActivityMode,
+    PressureLevel,
+    ResourcePolicy,
+    ResourceProfile,
+    ResourceState,
+    TaskPriority,
+)
+
+__all__ = [
+    "ActivityMode",
+    "BoundedMemoryCache",
+    "FileChangeDebouncer",
+    "PressureLevel",
+    "RequestCoalescer",
+    "ResourceGovernor",
+    "ResourcePolicy",
+    "ResourceProfile",
+    "ResourceState",
+    "TaskPriority",
+    "get_global_coalescer",
+    "get_global_governor",
+    "get_graph_cache",
+    "get_parse_cache",
+    "get_process_memory_mb",
+]

codegraph/resources/cache.py

@@ -0,0 +1,117 @@
+"""Bounded LRU Memory Caches with Size Tracking and Eviction.
+
+Prevents unbounded memory growth from ParseResults, graph neighborhoods,
+and retrieval artifacts during sustained coding sessions.
+"""
+from __future__ import annotations
+
+import sys
+import threading
+from collections import OrderedDict
+from collections.abc import Callable
+from typing import Any
+
+
+def _approx_size(obj: Any) -> int:
+    """Approximate memory footprint of an object."""
+    try:
+        if isinstance(obj, (str, bytes)):
+            return len(obj)
+        elif hasattr(obj, "__sizeof__"):
+            return int(obj.__sizeof__())
+        return sys.getsizeof(obj, 128)
+    except Exception:
+        return 128
+
+
+class BoundedMemoryCache[K, V]:
+    """Thread-safe LRU cache with both item count and memory byte limits."""
+
+    def __init__(self, max_items: int = 500, max_bytes: int = 50 * 1024 * 1024) -> None:
+        self.max_items = max_items
+        self.max_bytes = max_bytes
+        self._lock = threading.Lock()
+        self._cache: OrderedDict[K, tuple[V, int]] = OrderedDict()
+        self._current_bytes: int = 0
+        self._hits: int = 0
+        self._misses: int = 0
+
+    def get(self, key: K) -> V | None:
+        with self._lock:
+            if key not in self._cache:
+                self._misses += 1
+                return None
+            val, size = self._cache.pop(key)
+            self._cache[key] = (val, size)  # move to end (MRU)
+            self._hits += 1
+            return val
+
+    def put(self, key: K, value: V, size_bytes: int | None = None) -> None:
+        sz = size_bytes if size_bytes is not None else _approx_size(value)
+        with self._lock:
+            if key in self._cache:
+                _, old_sz = self._cache.pop(key)
+                self._current_bytes -= old_sz
+
+            self._cache[key] = (value, sz)
+            self._current_bytes += sz
+
+            # Evict until limits are satisfied
+            while len(self._cache) > self.max_items or (self._current_bytes > self.max_bytes and len(self._cache) > 1):
+                _, (_, evicted_sz) = self._cache.popitem(last=False)  # pop LRU
+                self._current_bytes -= evicted_sz
+
+    def set(self, key: K, value: V, size_bytes: int | None = None) -> None:
+        """Alias for put."""
+        self.put(key, value, size_bytes)
+
+    def invalidate(self, predicate: Callable[[K], bool]) -> int:
+        removed = 0
+        with self._lock:
+            keys_to_del = [k for k in self._cache if predicate(k)]
+            for k in keys_to_del:
+                _, sz = self._cache.pop(k)
+                self._current_bytes -= sz
+                removed += 1
+        return removed
+
+    def clear(self) -> None:
+        with self._lock:
+            self._cache.clear()
+            self._current_bytes = 0
+
+    def stats(self) -> dict[str, object]:
+        with self._lock:
+            return {
+                "items": len(self._cache),
+                "max_items": self.max_items,
+                "current_mb": round(self._current_bytes / (1024 * 1024), 2),
+                "max_mb": round(self.max_bytes / (1024 * 1024), 2),
+                "hits": self._hits,
+                "misses": self._misses,
+            }
+
+
+# ---------------------------------------------------------------------------
+# Global Specialized Caches
+# ---------------------------------------------------------------------------
+
+# ParseResult cache: (source_hash, parser_version, language) -> ParseResult
+_PARSE_CACHE: BoundedMemoryCache[tuple[str, str, str], Any] = BoundedMemoryCache(
+    max_items=300,
+    max_bytes=30 * 1024 * 1024,  # 30 MB
+)
+
+# Graph neighborhood cache: (repo_generation, symbol_id, relationship, depth) -> list[dict]
+_GRAPH_CACHE: BoundedMemoryCache[tuple[int, str, str, int], Any] = BoundedMemoryCache(
+    max_items=500,
+    max_bytes=20 * 1024 * 1024,  # 20 MB
+)
+
+
+def get_parse_cache() -> BoundedMemoryCache[tuple[str, str, str], Any]:
+    return _PARSE_CACHE
+
+
+def get_graph_cache() -> BoundedMemoryCache[tuple[int, str, str, int], Any]:
+    return _GRAPH_CACHE

codegraph/resources/coalescer.py

@@ -0,0 +1,83 @@
+"""Thread-safe Request Coalescing and In-Flight Flight Sharing.
+
+Prevents duplicate concurrent executions of identical read or compilation requests
+by allowing concurrent callers to share a single in-flight computation.
+"""
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from typing import Any
+
+
+class _InFlight[T]:
+    def __init__(self) -> None:
+        self.event = threading.Event()
+        self.result: T | None = None
+        self.error: BaseException | None = None
+
+
+class RequestCoalescer:
+    """Coalesces identical concurrent tasks into a single execution."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._flights: dict[str, _InFlight[Any]] = {}
+        self._coalesced_count: int = 0
+        self._total_requests: int = 0
+
+    def coalesce[T](self, key: str, fn: Callable[[], T]) -> T:
+        """Execute fn() or wait for an identical in-flight execution under the given key."""
+        with self._lock:
+            self._total_requests += 1
+            flight: _InFlight[T] | None = self._flights.get(key)
+            if flight is not None:
+                is_leader = False
+                self._coalesced_count += 1
+            else:
+                is_leader = True
+                flight = _InFlight[T]()
+                self._flights[key] = flight
+
+        if not is_leader:
+            # Wait for leader to complete computation
+            flight.event.wait()
+            if flight.error is not None:
+                raise flight.error
+            return flight.result  # type: ignore[return-value]
+
+        # Leader executes fn()
+        try:
+            res = fn()
+            flight.result = res
+            return res
+        except BaseException as exc:
+            flight.error = exc
+            raise
+        finally:
+            with self._lock:
+                self._flights.pop(key, None)
+            flight.event.set()
+
+    def in_flight_count(self) -> int:
+        with self._lock:
+            return len(self._flights)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._flights.clear()
+
+    def stats(self) -> dict[str, object]:
+        with self._lock:
+            return {
+                "in_flight": len(self._flights),
+                "total_requests": self._total_requests,
+                "coalesced_requests": self._coalesced_count,
+            }
+
+
+_GLOBAL_COALESCER = RequestCoalescer()
+
+
+def get_global_coalescer() -> RequestCoalescer:
+    return _GLOBAL_COALESCER

codegraph/resources/debouncer.py

@@ -0,0 +1,98 @@
+"""File Change Debouncer and Burst Coalescer.
+
+Coalesces rapid file system save events from code editors into bounded batches
+to prevent repeated, wasteful index cycles.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+
+class FileChangeDebouncer:
+    """Thread-safe debounce accumulator for editor save bursts."""
+
+    def __init__(
+        self,
+        debounce_ms: int = 500,
+        max_batch_size: int = 100,
+        on_batch: Callable[[set[str]], None] | None = None,
+    ) -> None:
+        self.debounce_ms = debounce_ms
+        self.max_batch_size = max_batch_size
+        self.on_batch = on_batch
+
+        self._lock = threading.Lock()
+        self._pending_paths: set[str] = set()
+        self._timer: threading.Timer | None = None
+        self._last_event_time: float = 0.0
+
+    def add_change(self, path: str | Path) -> None:
+        """Record a file modification or save event."""
+        p_str = path.as_posix() if isinstance(path, Path) else str(path)
+        with self._lock:
+            self._pending_paths.add(p_str)
+            self._last_event_time = time.time()
+
+            if len(self._pending_paths) >= self.max_batch_size:
+                self._dispatch_locked()
+                return
+
+            if self._timer is not None:
+                self._timer.cancel()
+
+            delay_sec = self.debounce_ms / 1000.0
+            self._timer = threading.Timer(delay_sec, self._on_timer_fired)
+            self._timer.daemon = True
+            self._timer.start()
+
+    def _on_timer_fired(self) -> None:
+        with self._lock:
+            self._dispatch_locked()
+
+    def _dispatch_locked(self) -> None:
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+
+        if not self._pending_paths:
+            return
+
+        batch = set(self._pending_paths)
+        self._pending_paths.clear()
+
+        if self.on_batch:
+            # Dispatch outside lock or in thread to avoid deadlocks
+            threading.Thread(target=self.on_batch, args=(batch,), daemon=True).start()
+
+    def flush(self) -> set[str]:
+        """Synchronously drain all pending coalesced paths."""
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+            batch = set(self._pending_paths)
+            self._pending_paths.clear()
+            return batch
+
+    def pending_count(self) -> int:
+        with self._lock:
+            return len(self._pending_paths)
+
+    def record_change(self, path: str | Path) -> None:
+        """Alias for add_change."""
+        self.add_change(path)
+
+    def start(self, on_batch: Callable[[set[str]], None]) -> None:
+        """Configure or update batch callback."""
+        with self._lock:
+            self.on_batch = on_batch
+
+    def stop(self) -> None:
+        """Cancel any pending timer."""
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None

codegraph/resources/governor.py

@@ -0,0 +1,232 @@
+"""Central Resource Governor for CodeGraph MCP.
+
+Protects developer laptop responsiveness during active coding by bounding concurrency,
+throttling background indexing, managing process memory, and cooperatively yielding.
+"""
+from __future__ import annotations
+
+import resource
+import sys
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from .policy import (
+    ActivityMode,
+    PressureLevel,
+    ResourcePolicy,
+    ResourceProfile,
+    ResourceState,
+    TaskPriority,
+)
+
+
+def get_process_memory_mb() -> float:
+    """Return estimated resident process memory in megabytes portably."""
+    try:
+        usage = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+        if sys.platform == "darwin":
+            return round(usage / (1024 * 1024), 2)
+        else:
+            return round(usage / 1024, 2)
+    except Exception:
+        return 0.0
+
+
+class ResourceGovernor:
+    """Thread-safe central resource governor and priority scheduler."""
+
+    def __init__(self, policy: ResourcePolicy | None = None) -> None:
+        self.policy = policy or ResourcePolicy.for_profile(ResourceProfile.BALANCED)
+        self._lock = threading.RLock()
+        self._condition = threading.Condition(self._lock)
+
+        self._active_interactive: int = 0
+        self._active_background: int = 0
+        self._queued_tasks: int = 0
+        self._indexing_active: bool = False
+        self._watcher_active: bool = False
+
+        self._last_interactive_time: float = 0.0
+        self._last_file_change_time: float = 0.0
+
+        self._recent_cpu_time_ms: float = 0.0
+        self._recent_wall_time_ms: float = 0.0
+
+        self._interactive_sem = threading.Semaphore(self.policy.max_interactive_workers)
+        self._background_sem = threading.Semaphore(self.policy.max_background_workers)
+
+    def set_policy(self, policy: ResourcePolicy) -> None:
+        """Update runtime policy dynamically."""
+        with self._lock:
+            self.policy = policy
+            self._interactive_sem = threading.Semaphore(policy.max_interactive_workers)
+            self._background_sem = threading.Semaphore(policy.max_background_workers)
+            self._condition.notify_all()
+
+    def record_activity(self, kind: str = "interactive") -> None:
+        """Record non-invasive activity to maintain active coding state."""
+        now = time.time()
+        with self._lock:
+            if kind == "file_change":
+                self._last_file_change_time = now
+            else:
+                self._last_interactive_time = now
+
+    def get_activity_mode(self) -> ActivityMode:
+        """Infer activity mode from recent MCP and file change events."""
+        with self._lock:
+            now = time.time()
+            recent_interactive = (now - self._last_interactive_time) < 45.0
+            recent_files = (now - self._last_file_change_time) < 45.0
+            if recent_interactive or recent_files:
+                return ActivityMode.ACTIVE_CODING
+            if self._active_background > 0 or self._indexing_active:
+                return ActivityMode.BACKGROUND
+            return ActivityMode.IDLE
+
+    def is_active_coding(self) -> bool:
+        return self.get_activity_mode() == ActivityMode.ACTIVE_CODING
+
+    def get_pressure(self) -> PressureLevel:
+        """Compute system resource pressure with conservative hysteresis."""
+        mem_mb = get_process_memory_mb()
+        limit_mb = self.policy.max_memory_mb
+
+        with self._lock:
+            active_inter = self._active_interactive
+
+        if limit_mb and mem_mb >= limit_mb * 0.90:
+            return PressureLevel.CRITICAL
+        if active_inter >= self.policy.max_interactive_workers * 2:
+            return PressureLevel.CRITICAL
+
+        if limit_mb and mem_mb >= limit_mb * 0.75:
+            return PressureLevel.HIGH
+        if active_inter > self.policy.max_interactive_workers:
+            return PressureLevel.HIGH
+
+        if limit_mb and mem_mb >= limit_mb * 0.60:
+            return PressureLevel.ELEVATED
+        if active_inter > 0:
+            return PressureLevel.ELEVATED
+
+        return PressureLevel.NORMAL
+
+    def should_throttle(self, priority: TaskPriority = TaskPriority.BACKGROUND) -> bool:
+        """Check whether a background or maintenance task should throttle or yield."""
+        if priority in (TaskPriority.INTERACTIVE_HIGH, TaskPriority.INTERACTIVE_NORMAL):
+            return False
+        pressure = self.get_pressure()
+        if pressure in (PressureLevel.CRITICAL, PressureLevel.HIGH):
+            return True
+        return self.is_active_coding()
+
+    def yield_if_needed(self, priority: TaskPriority = TaskPriority.BACKGROUND) -> None:
+        """Cooperative yield point for long-running iterative tasks."""
+        if priority in (TaskPriority.INTERACTIVE_HIGH, TaskPriority.INTERACTIVE_NORMAL):
+            return
+
+        pressure = self.get_pressure()
+        if pressure == PressureLevel.CRITICAL:
+            # Under critical pressure, background work yields for 100ms
+            time.sleep(0.10)
+        elif pressure == PressureLevel.HIGH or self.is_active_coding():
+            # Under high pressure or active coding, yield 20ms to free up CPU
+            time.sleep(0.02)
+        else:
+            # Minimal cooperative yield to let OS reschedule other threads
+            time.sleep(0.001)
+
+    def get_state(self) -> ResourceState:
+        """Snapshot current resource state."""
+        mem = get_process_memory_mb()
+        pressure = self.get_pressure()
+        mode = self.get_activity_mode()
+        with self._lock:
+            return ResourceState(
+                policy_profile=self.policy.profile.value,
+                active_interactive_requests=self._active_interactive,
+                active_background_tasks=self._active_background,
+                queued_tasks=self._queued_tasks,
+                recent_cpu_time_ms=round(self._recent_cpu_time_ms, 2),
+                recent_wall_time_ms=round(self._recent_wall_time_ms, 2),
+                estimated_memory_mb=mem,
+                pressure_level=pressure.value,
+                activity_mode=mode.value,
+                indexing_active=self._indexing_active,
+                watcher_active=self._watcher_active,
+            )
+
+    @contextmanager
+    def task_scope(
+        self,
+        priority: TaskPriority = TaskPriority.INTERACTIVE_HIGH,
+        task_id: str | None = None,
+    ) -> Iterator[None]:
+        """Scoped execution guard that handles priority scheduling, tracking, and yielding."""
+        del task_id
+        is_interactive = priority in (TaskPriority.INTERACTIVE_HIGH, TaskPriority.INTERACTIVE_NORMAL)
+        sem = self._interactive_sem if is_interactive else self._background_sem
+
+        with self._lock:
+            self._queued_tasks += 1
+            if is_interactive:
+                self.record_activity("interactive")
+
+        sem.acquire()
+        try:
+            throttle = False
+            with self._lock:
+                self._queued_tasks = max(0, self._queued_tasks - 1)
+                if is_interactive:
+                    self._active_interactive += 1
+                else:
+                    self._active_background += 1
+                    if self.is_active_coding() and self.policy.aggressive_throttling:
+                        throttle = True
+            if throttle:
+                time.sleep(0.01)
+
+            t0_cpu = time.process_time()
+            t0_wall = time.perf_counter()
+            try:
+                yield
+            finally:
+                elapsed_cpu = (time.process_time() - t0_cpu) * 1000
+                elapsed_wall = (time.perf_counter() - t0_wall) * 1000
+                with self._lock:
+                    if is_interactive:
+                        self._active_interactive = max(0, self._active_interactive - 1)
+                        self._last_interactive_time = time.time()
+                    else:
+                        self._active_background = max(0, self._active_background - 1)
+                    self._recent_cpu_time_ms = elapsed_cpu
+                    self._recent_wall_time_ms = elapsed_wall
+                    self._condition.notify_all()
+        finally:
+            sem.release()
+
+    def set_indexing_active(self, active: bool) -> None:
+        with self._lock:
+            self._indexing_active = active
+
+    def set_watcher_active(self, active: bool) -> None:
+        with self._lock:
+            self._watcher_active = active
+
+
+_GLOBAL_GOVERNOR: ResourceGovernor | None = None
+_GOVERNOR_LOCK = threading.Lock()
+
+
+def get_global_governor(policy: ResourcePolicy | None = None) -> ResourceGovernor:
+    """Access the singleton resource governor for the current process."""
+    global _GLOBAL_GOVERNOR
+    with _GOVERNOR_LOCK:
+        if _GLOBAL_GOVERNOR is None:
+            _GLOBAL_GOVERNOR = ResourceGovernor(policy)
+        elif policy is not None:
+            _GLOBAL_GOVERNOR.set_policy(policy)
+        return _GLOBAL_GOVERNOR

codegraph/resources/policy.py

@@ -0,0 +1,123 @@
+"""Resource Policies, Profiles, Task Priorities, and State Models.
+
+Defines bounded execution budgets, memory limits, concurrency profiles,
+and cooperative pressure levels without platform-specific hardware assumptions.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from enum import StrEnum
+
+
+class ResourceProfile(StrEnum):
+    LIGHT = "LIGHT"
+    BALANCED = "BALANCED"
+    PERFORMANCE = "PERFORMANCE"
+
+
+class PressureLevel(StrEnum):
+    NORMAL = "NORMAL"
+    ELEVATED = "ELEVATED"
+    HIGH = "HIGH"
+    CRITICAL = "CRITICAL"
+
+
+class TaskPriority(StrEnum):
+    INTERACTIVE_HIGH = "INTERACTIVE_HIGH"
+    INTERACTIVE_NORMAL = "INTERACTIVE_NORMAL"
+    BACKGROUND = "BACKGROUND"
+    MAINTENANCE = "MAINTENANCE"
+
+
+class ActivityMode(StrEnum):
+    ACTIVE_CODING = "ACTIVE_CODING"
+    IDLE = "IDLE"
+    BACKGROUND = "BACKGROUND"
+
+
+@dataclass(frozen=True)
+class ResourcePolicy:
+    profile: ResourceProfile = ResourceProfile.BALANCED
+    max_interactive_workers: int = 2
+    max_background_workers: int = 1
+    max_files_per_incremental_batch: int = 25
+    max_graph_nodes_per_query: int = 300
+    max_graph_edges_per_query: int = 1200
+    max_git_commits: int = 15
+    max_memory_mb: int = 1024
+    max_cpu_time_ms_per_request: int = 5000
+    background_enabled: bool = True
+    aggressive_throttling: bool = True
+    debounce_ms: int = 500
+
+    @classmethod
+    def for_profile(cls, profile: str | ResourceProfile) -> ResourcePolicy:
+        p = ResourceProfile(str(profile).upper()) if isinstance(profile, str) else profile
+        if p == ResourceProfile.LIGHT:
+            return cls(
+                profile=ResourceProfile.LIGHT,
+                max_interactive_workers=1,
+                max_background_workers=1,
+                max_files_per_incremental_batch=10,
+                max_graph_nodes_per_query=100,
+                max_graph_edges_per_query=400,
+                max_git_commits=5,
+                max_memory_mb=512,
+                max_cpu_time_ms_per_request=2000,
+                background_enabled=True,
+                aggressive_throttling=True,
+                debounce_ms=800,
+            )
+        elif p == ResourceProfile.PERFORMANCE:
+            return cls(
+                profile=ResourceProfile.PERFORMANCE,
+                max_interactive_workers=4,
+                max_background_workers=2,
+                max_files_per_incremental_batch=100,
+                max_graph_nodes_per_query=1000,
+                max_graph_edges_per_query=5000,
+                max_git_commits=50,
+                max_memory_mb=4096,
+                max_cpu_time_ms_per_request=15000,
+                background_enabled=True,
+                aggressive_throttling=False,
+                debounce_ms=250,
+            )
+        else:
+            return cls(
+                profile=ResourceProfile.BALANCED,
+                max_interactive_workers=2,
+                max_background_workers=1,
+                max_files_per_incremental_batch=25,
+                max_graph_nodes_per_query=300,
+                max_graph_edges_per_query=1200,
+                max_git_commits=15,
+                max_memory_mb=1024,
+                max_cpu_time_ms_per_request=5000,
+                background_enabled=True,
+                aggressive_throttling=True,
+                debounce_ms=500,
+            )
+
+    def as_dict(self) -> dict[str, object]:
+        d = asdict(self)
+        d["profile"] = self.profile.value
+        return d
+
+
+@dataclass(frozen=True)
+class ResourceState:
+    policy_profile: str = ResourceProfile.BALANCED.value
+    active_interactive_requests: int = 0
+    active_background_tasks: int = 0
+    queued_tasks: int = 0
+    recent_cpu_time_ms: float = 0.0
+    recent_wall_time_ms: float = 0.0
+    estimated_memory_mb: float = 0.0
+    pressure_level: str = PressureLevel.NORMAL.value
+    activity_mode: str = ActivityMode.IDLE.value
+    indexing_active: bool = False
+    watcher_active: bool = False
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)