codecortex-context-engine 0.1.0a1__py3-none-any.whl

codecortex/backends/pool.py

@@ -0,0 +1,128 @@
+"""Warm process/session pool for long-lived isolated MCP backends."""
+
+from __future__ import annotations
+
+import atexit
+import threading
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from codecortex.backends.manager import BackendManager
+from codecortex.backends.mcp_client import MCPStdioClient
+from codecortex.backends.spec import BackendSpec
+
+
+@dataclass(slots=True)
+class _Session:
+    client: MCPStdioClient
+    lock: threading.RLock
+
+
+class BackendSessionPool:
+    """Keep MCP backend processes warm and serialize traffic per process.
+
+    A failed request invalidates the process and retries once with a clean session. This
+    removes repeated process startup/initialize latency while keeping recovery bounded.
+    """
+
+    def __init__(self, manager: BackendManager) -> None:
+        self.manager = manager
+        self._sessions: dict[tuple[object, ...], _Session] = {}
+        self._lock = threading.RLock()
+        atexit.register(self.close_all)
+
+    @staticmethod
+    def _key(
+        spec: BackendSpec,
+        server_args: Sequence[str],
+        cwd: Path | None,
+        env: Mapping[str, str] | None,
+    ) -> tuple[object, ...]:
+        return (
+            spec.key,
+            spec.revision,
+            tuple(server_args),
+            str(cwd.resolve()) if cwd else None,
+            tuple(sorted((env or {}).items())),
+        )
+
+    def _session(
+        self,
+        spec: BackendSpec,
+        server_args: Sequence[str],
+        *,
+        cwd: Path | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> tuple[tuple[object, ...], _Session]:
+        key = self._key(spec, server_args, cwd, env)
+        with self._lock:
+            session = self._sessions.get(key)
+            if session is None:
+                client = MCPStdioClient(
+                    self.manager,
+                    spec,
+                    server_args,
+                    cwd=cwd,
+                    env=env,
+                )
+                client.start()
+                session = _Session(client=client, lock=threading.RLock())
+                self._sessions[key] = session
+            return key, session
+
+    def invalidate(self, key: tuple[object, ...]) -> None:
+        with self._lock:
+            session = self._sessions.pop(key, None)
+        if session is not None:
+            session.client.close()
+
+    def call_tool(
+        self,
+        spec: BackendSpec,
+        server_args: Sequence[str],
+        name: str,
+        arguments: Mapping[str, Any] | None = None,
+        *,
+        cwd: Path | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        last: Exception | None = None
+        for attempt in range(2):
+            key, session = self._session(spec, server_args, cwd=cwd, env=env)
+            try:
+                with session.lock:
+                    return session.client.call_tool(name, arguments)
+            except Exception as exc:
+                last = exc
+                self.invalidate(key)
+                if attempt:
+                    raise
+        assert last is not None
+        raise last
+
+    def tools(
+        self,
+        spec: BackendSpec,
+        server_args: Sequence[str],
+        *,
+        cwd: Path | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> list[dict[str, Any]]:
+        key, session = self._session(spec, server_args, cwd=cwd, env=env)
+        try:
+            with session.lock:
+                return session.client.tools()
+        except Exception:
+            self.invalidate(key)
+            key, session = self._session(spec, server_args, cwd=cwd, env=env)
+            with session.lock:
+                return session.client.tools()
+
+    def close_all(self) -> None:
+        with self._lock:
+            sessions = list(self._sessions.values())
+            self._sessions.clear()
+        for session in sessions:
+            session.client.close()

codecortex/backends/spec.py

@@ -0,0 +1,83 @@
+"""Configuration-driven optional backend specifications."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class BackendSpec:
+    key: str
+    capabilities: tuple[str, ...]
+    package: str = ""
+    source_url: str = ""
+    revision: str = ""
+    command: str = ""
+    license_id: str = ""
+    extras: tuple[str, ...] = ()
+    python: str = "3.13"
+    vendor_path: str | None = None
+
+    @property
+    def configured(self) -> bool:
+        return bool(
+            self.package
+            and self.source_url
+            and len(self.revision) == 40
+            and self.command
+        )
+
+    @property
+    def source_requirement(self) -> str:
+        if not self.configured:
+            raise RuntimeError(f"backend {self.key!r} is not configured")
+        if not self.extras:
+            return f"git+{self.source_url}@{self.revision}"
+        extras = ",".join(self.extras)
+        return f"{self.package}[{extras}] @ git+{self.source_url}@{self.revision}"
+
+
+def _external_spec(
+    key: str,
+    capabilities: tuple[str, ...],
+    *,
+    default_extras: tuple[str, ...] = (),
+) -> BackendSpec:
+    prefix = f"CODECORTEX_{key.upper()}_BACKEND"
+    extras_value = os.getenv(f"{prefix}_EXTRAS", "").strip()
+    extras = (
+        tuple(part.strip() for part in extras_value.split(",") if part.strip())
+        if extras_value
+        else default_extras
+    )
+    vendor_path = os.getenv(f"{prefix}_LOCAL_PATH", "").strip() or None
+    return BackendSpec(
+        key=key,
+        capabilities=capabilities,
+        package=os.getenv(f"{prefix}_PACKAGE", "").strip(),
+        source_url=os.getenv(f"{prefix}_SOURCE_URL", "").strip(),
+        revision=os.getenv(f"{prefix}_REVISION", "").strip(),
+        command=os.getenv(f"{prefix}_COMMAND", "").strip(),
+        license_id=os.getenv(f"{prefix}_LICENSE", "").strip(),
+        extras=extras,
+        python=os.getenv(f"{prefix}_PYTHON", "3.13").strip() or "3.13",
+        vendor_path=vendor_path,
+    )
+
+
+BACKENDS: dict[str, BackendSpec] = {
+    "graph": _external_spec(
+        "graph",
+        ("ast", "graph", "query", "path", "explain", "incremental"),
+    ),
+    "symbols": _external_spec(
+        "symbols",
+        ("lsp", "symbols", "references", "diagnostics", "editing", "refactor"),
+    ),
+    "context": _external_spec(
+        "context",
+        ("compression", "routing", "reversible", "memory", "proxy", "mcp"),
+        default_extras=("mcp", "code", "memory", "relevance"),
+    ),
+}

codecortex/backends/symbols.py

@@ -0,0 +1,189 @@
+"""IDE-grade semantic symbol backend adapter with guarded edits."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from codecortex.backends.base import ManagedAdapterMixin
+from codecortex.backends.manager import BackendManager
+from codecortex.backends.mcp_client import MCPStdioClient
+from codecortex.backends.pool import BackendSessionPool
+from codecortex.backends.spec import BACKENDS
+from codecortex.core.contracts import Engine
+from codecortex.core.models import AgentRequest, Capability, ContextChunk, EngineResult, RequestKind
+
+
+class SymbolBackendAdapter(ManagedAdapterMixin, Engine):
+    capability = Capability.SYMBOLS
+    required_tools = {"find_symbol", "find_referencing_symbols"}
+    editing_tools = {
+        "rename_symbol",
+        "replace_symbol_body",
+        "insert_before_symbol",
+        "insert_after_symbol",
+    }
+
+    def __init__(self, project_root: Path, manager: BackendManager | None = None) -> None:
+        self.project_root = project_root.resolve()
+        self.manager = manager or BackendManager()
+        self.spec = BACKENDS["symbols"]
+        self.pool = BackendSessionPool(self.manager)
+
+    async def health(self) -> bool:
+        return await asyncio.to_thread(self.manager.probe, self.spec, False)
+
+    def server_args(self) -> tuple[str, ...]:
+        return (
+            "start-mcp-server",
+            "--transport",
+            "stdio",
+            "--project",
+            str(self.project_root),
+            "--enable-web-dashboard",
+            "false",
+            "--open-web-dashboard",
+            "false",
+        )
+
+    def tools(self) -> list[dict[str, Any]]:
+        tools = self.pool.tools(
+            self.spec,
+            self.server_args(),
+            cwd=self.project_root,
+        )
+        self.require_tools(tools, self.required_tools)
+        return tools
+
+    def call(self, tool: str, arguments: Mapping[str, Any]) -> dict[str, Any]:
+        return self.pool.call_tool(
+            self.spec,
+            self.server_args(),
+            tool,
+            arguments,
+            cwd=self.project_root,
+        )
+
+    def _relative_path(self, value: str) -> str:
+        candidate = (self.project_root / value).resolve()
+        try:
+            relative = candidate.relative_to(self.project_root)
+        except ValueError as exc:
+            raise ValueError("symbol edits must stay inside the project root") from exc
+        if not candidate.exists():
+            raise ValueError(f"path does not exist: {value}")
+        if not candidate.is_file():
+            raise ValueError(f"expected a file path: {value}")
+        return relative.as_posix()
+
+    def _require_edit_tool(self, name: str) -> None:
+        available = {str(item.get("name")) for item in self.tools()}
+        if name not in available:
+            raise RuntimeError(f"symbol backend does not expose required edit tool: {name}")
+
+    def preflight_symbol(self, name_path: str, relative_path: str) -> dict[str, Any]:
+        relative_path = self._relative_path(relative_path)
+        return self.call(
+            "find_symbol",
+            {
+                "name_path_pattern": name_path,
+                "relative_path": relative_path,
+                "include_body": True,
+                "max_matches": 2,
+            },
+        )
+
+    def rename_symbol(self, name_path: str, relative_path: str, new_name: str) -> dict[str, Any]:
+        relative_path = self._relative_path(relative_path)
+        if not new_name.strip():
+            raise ValueError("new_name cannot be empty")
+        self._require_edit_tool("rename_symbol")
+        self.preflight_symbol(name_path, relative_path)
+        return self.call(
+            "rename_symbol",
+            {"name_path": name_path, "relative_path": relative_path, "new_name": new_name},
+        )
+
+    def replace_symbol_body(self, name_path: str, relative_path: str, body: str) -> dict[str, Any]:
+        relative_path = self._relative_path(relative_path)
+        if not body.strip():
+            raise ValueError("replacement body cannot be empty")
+        self._require_edit_tool("replace_symbol_body")
+        self.preflight_symbol(name_path, relative_path)
+        return self.call(
+            "replace_symbol_body",
+            {"name_path": name_path, "relative_path": relative_path, "body": body},
+        )
+
+    def insert_before_symbol(self, name_path: str, relative_path: str, body: str) -> dict[str, Any]:
+        relative_path = self._relative_path(relative_path)
+        self._require_edit_tool("insert_before_symbol")
+        self.preflight_symbol(name_path, relative_path)
+        return self.call(
+            "insert_before_symbol",
+            {"name_path": name_path, "relative_path": relative_path, "body": body},
+        )
+
+    def insert_after_symbol(self, name_path: str, relative_path: str, body: str) -> dict[str, Any]:
+        relative_path = self._relative_path(relative_path)
+        self._require_edit_tool("insert_after_symbol")
+        self.preflight_symbol(name_path, relative_path)
+        return self.call(
+            "insert_after_symbol",
+            {"name_path": name_path, "relative_path": relative_path, "body": body},
+        )
+
+    async def execute(self, request: AgentRequest) -> EngineResult:
+        return await asyncio.to_thread(self._execute_sync, request)
+
+    def _execute_sync(self, request: AgentRequest) -> EngineResult:
+        explicit_tool = request.metadata.get("symbol_tool")
+        explicit_args = request.metadata.get("symbol_arguments")
+        if isinstance(explicit_tool, str):
+            arguments = dict(explicit_args) if isinstance(explicit_args, Mapping) else {}
+            result = self.call(explicit_tool, arguments)
+            tool = explicit_tool
+        else:
+            tool, arguments = self._plan(request)
+            result = self.call(tool, arguments)
+        content = MCPStdioClient.content_text(result) or json.dumps(result, ensure_ascii=False)
+        return EngineResult(
+            capability=self.capability,
+            content=content,
+            chunks=[
+                ContextChunk(
+                    source=f"symbol:{tool}",
+                    content=content,
+                    tokens=max(1, len(content) // 4),
+                    relevance=0.98,
+                    metadata={"backend": self.spec.key, "tool": tool},
+                )
+            ]
+            if content
+            else [],
+            metadata={"backend": self.spec.key, "revision": self.spec.revision, "tool": tool},
+        )
+
+    @staticmethod
+    def _plan(request: AgentRequest) -> tuple[str, dict[str, Any]]:
+        relative_path = request.metadata.get("relative_path")
+        if request.kind in {RequestKind.REFACTOR, RequestKind.CHANGE}:
+            return "find_symbol", {
+                "name_path_pattern": request.query,
+                "include_body": True,
+                **({"relative_path": relative_path} if isinstance(relative_path, str) else {}),
+            }
+        if request.metadata.get("references") and isinstance(relative_path, str):
+            return "find_referencing_symbols", {
+                "name_path": request.query,
+                "relative_path": relative_path,
+            }
+        return "find_symbol", {
+            "name_path_pattern": request.query,
+            "include_body": request.kind in {RequestKind.DEBUG, RequestKind.REVIEW},
+            "depth": 1,
+            **({"relative_path": relative_path} if isinstance(relative_path, str) else {}),
+        }

codecortex/benchmark.py

@@ -0,0 +1,211 @@
+"""Reproducible repository intelligence benchmark harness."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from time import perf_counter
+from typing import Protocol
+
+from codecortex.indexing.indexer import ProjectIndexer
+
+_TEXT_SUFFIXES = {
+    ".py", ".js", ".jsx", ".ts", ".tsx", ".go", ".rs", ".java",
+    ".c", ".h", ".cc", ".cpp", ".hpp", ".cs", ".php", ".rb",
+    ".md", ".toml", ".yaml", ".yml", ".json",
+}
+_EXCLUDED = {".git", ".codecortex", ".venv", "venv", "node_modules", "dist", "build"}
+
+
+@dataclass(frozen=True, slots=True)
+class BenchmarkCase:
+    id: str
+    query: str
+    expected_paths: tuple[str, ...] = ()
+    expected_symbols: tuple[str, ...] = ()
+
+    @classmethod
+    def from_dict(cls, value: dict[str, object]) -> BenchmarkCase:
+        return cls(
+            id=str(value["id"]),
+            query=str(value["query"]),
+            expected_paths=tuple(str(item) for item in value.get("expected_paths", [])),
+            expected_symbols=tuple(str(item) for item in value.get("expected_symbols", [])),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class StrategyResult:
+    strategy: str
+    case_id: str
+    duration_ms: float
+    context_tokens: int
+    files_read: int
+    tool_calls: int
+    path_recall: float
+    symbol_recall: float
+    success: bool
+
+
+@dataclass(frozen=True, slots=True)
+class BenchmarkReport:
+    results: tuple[StrategyResult, ...]
+
+    def summary(self) -> dict[str, dict[str, float]]:
+        grouped: dict[str, list[StrategyResult]] = {}
+        for result in self.results:
+            grouped.setdefault(result.strategy, []).append(result)
+        summary: dict[str, dict[str, float]] = {}
+        for name, rows in grouped.items():
+            count = max(1, len(rows))
+            summary[name] = {
+                "cases": float(len(rows)),
+                "success_rate": sum(row.success for row in rows) / count,
+                "avg_duration_ms": sum(row.duration_ms for row in rows) / count,
+                "avg_context_tokens": sum(row.context_tokens for row in rows) / count,
+                "avg_files_read": sum(row.files_read for row in rows) / count,
+                "avg_tool_calls": sum(row.tool_calls for row in rows) / count,
+                "avg_path_recall": sum(row.path_recall for row in rows) / count,
+                "avg_symbol_recall": sum(row.symbol_recall for row in rows) / count,
+            }
+        return summary
+
+    def save(self, output: Path) -> None:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "summary": self.summary(),
+            "results": [asdict(result) for result in self.results],
+        }
+        output.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+class BenchmarkStrategy(Protocol):
+    name: str
+
+    def run(self, case: BenchmarkCase) -> StrategyResult: ...
+
+
+def _recall(expected: tuple[str, ...], actual: set[str]) -> float:
+    if not expected:
+        return 1.0
+    normalized = {item.lower() for item in actual}
+    hits = sum(
+        1
+        for item in expected
+        if item.lower() in normalized
+        or any(item.lower() in candidate for candidate in normalized)
+    )
+    return hits / len(expected)
+
+
+def _success(case: BenchmarkCase, path_recall: float, symbol_recall: float) -> bool:
+    paths_ok = not case.expected_paths or path_recall > 0
+    symbols_ok = not case.expected_symbols or symbol_recall > 0
+    return paths_ok and symbols_ok
+
+
+class FullTextBaseline:
+    """Simple full-repository lexical baseline used for measured comparisons."""
+
+    name = "full_text_baseline"
+
+    def __init__(self, root: Path, max_files: int = 10_000, result_limit: int = 50) -> None:
+        self.root = root.resolve()
+        self.max_files = max_files
+        self.result_limit = result_limit
+
+    def run(self, case: BenchmarkCase) -> StrategyResult:
+        started = perf_counter()
+        terms = {term.lower() for term in case.query.split() if len(term) > 2}
+        scored: list[tuple[int, str, str]] = []
+        files_read = 0
+        for path in self.root.rglob("*"):
+            if files_read >= self.max_files:
+                break
+            if not path.is_file() or path.suffix.lower() not in _TEXT_SUFFIXES:
+                continue
+            relative = path.relative_to(self.root)
+            if any(part in _EXCLUDED for part in relative.parts):
+                continue
+            try:
+                text = path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                continue
+            files_read += 1
+            lowered = text.lower()
+            path_text = relative.as_posix().lower()
+            score = sum(lowered.count(term) + (3 if term in path_text else 0) for term in terms)
+            if score:
+                scored.append((score, relative.as_posix(), text[:4000]))
+        scored.sort(key=lambda item: (-item[0], item[1]))
+        selected = scored[: self.result_limit]
+        paths = {path for _, path, _ in selected}
+        symbols: set[str] = set()
+        context = "\n".join(f"[{path}]\n{text}" for _, path, text in selected)
+        path_recall = _recall(case.expected_paths, paths)
+        symbol_recall = _recall(case.expected_symbols, symbols)
+        return StrategyResult(
+            strategy=self.name,
+            case_id=case.id,
+            duration_ms=(perf_counter() - started) * 1000,
+            context_tokens=max(0, len(context) // 4),
+            files_read=files_read,
+            tool_calls=1,
+            path_recall=path_recall,
+            symbol_recall=symbol_recall,
+            success=_success(case, path_recall, symbol_recall),
+        )
+
+
+class CodeCortexGraphStrategy:
+    name = "codecortex_graph"
+
+    def __init__(self, root: Path, result_limit: int = 50) -> None:
+        self.root = root.resolve()
+        self.result_limit = result_limit
+        self.graph = ProjectIndexer(self.root).build()
+
+    def run(self, case: BenchmarkCase) -> StrategyResult:
+        started = perf_counter()
+        matches = self.graph.search(case.query, self.result_limit)
+        paths = {node.path for node in matches if node.path}
+        symbols = {node.name for node in matches if node.kind not in {"file", "module", "reference"}}
+        lines = [
+            f"{node.kind} {node.name} {node.path or ''}:{node.line or ''}"
+            for node in matches
+        ]
+        context = "\n".join(lines)
+        path_recall = _recall(case.expected_paths, {path for path in paths if path})
+        symbol_recall = _recall(case.expected_symbols, symbols)
+        return StrategyResult(
+            strategy=self.name,
+            case_id=case.id,
+            duration_ms=(perf_counter() - started) * 1000,
+            context_tokens=max(0, len(context) // 4),
+            files_read=len({path for path in paths if path}),
+            tool_calls=1,
+            path_recall=path_recall,
+            symbol_recall=symbol_recall,
+            success=_success(case, path_recall, symbol_recall),
+        )
+
+
+class BenchmarkSuite:
+    def __init__(self, cases: list[BenchmarkCase], strategies: list[BenchmarkStrategy]) -> None:
+        self.cases = cases
+        self.strategies = strategies
+
+    @classmethod
+    def load(cls, path: Path, strategies: list[BenchmarkStrategy]) -> BenchmarkSuite:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        cases = [BenchmarkCase.from_dict(item) for item in payload["cases"]]
+        return cls(cases, strategies)
+
+    def run(self) -> BenchmarkReport:
+        results = tuple(
+            strategy.run(case)
+            for case in self.cases
+            for strategy in self.strategies
+        )
+        return BenchmarkReport(results)