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

codecortex/backends/graph.py

@@ -0,0 +1,107 @@
+"""Configurable repository graph backend adapter."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from codecortex.backends.base import ManagedAdapterMixin
+from codecortex.backends.manager import BackendManager
+from codecortex.backends.spec import BACKENDS
+from codecortex.core.contracts import Engine
+from codecortex.core.models import AgentRequest, Capability, ContextChunk, EngineResult
+
+
+class GraphBackendAdapter(ManagedAdapterMixin, Engine):
+    capability = Capability.REPOSITORY
+
+    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["graph"]
+
+    async def health(self) -> bool:
+        return await asyncio.to_thread(self.manager.probe, self.spec, False)
+
+    def _graph_path(self) -> Path:
+        configured = os.getenv(
+            "CODECORTEX_GRAPH_BACKEND_OUTPUT",
+            ".codecortex/backends/graph.json",
+        )
+        candidate = (self.project_root / configured).resolve()
+        try:
+            candidate.relative_to(self.project_root)
+        except ValueError:
+            raise ValueError("graph backend output must stay inside the project root") from None
+        return candidate
+
+    def build(self) -> dict[str, Any]:
+        self.manager.run(self.spec, (".",), cwd=self.project_root)
+        graph_path = self._graph_path()
+        if not graph_path.exists():
+            raise RuntimeError("graph backend completed without its configured graph payload")
+        payload = json.loads(graph_path.read_text(encoding="utf-8"))
+        if not isinstance(payload, dict):
+            raise RuntimeError("graph backend emitted an invalid graph payload")
+        return payload
+
+    def query(self, query: str) -> str:
+        return self.manager.run(
+            self.spec,
+            ("query", query),
+            cwd=self.project_root,
+            timeout_seconds=90,
+        ).stdout.strip()
+
+    def explain(self, node: str) -> str:
+        return self.manager.run(
+            self.spec,
+            ("explain", node),
+            cwd=self.project_root,
+            timeout_seconds=60,
+        ).stdout.strip()
+
+    def path(self, source: str, target: str) -> str:
+        return self.manager.run(
+            self.spec,
+            ("path", source, target),
+            cwd=self.project_root,
+            timeout_seconds=60,
+        ).stdout.strip()
+
+    async def execute(self, request: AgentRequest) -> EngineResult:
+        return await asyncio.to_thread(self._execute_sync, request)
+
+    def _execute_sync(self, request: AgentRequest) -> EngineResult:
+        mode = str(request.metadata.get("graph_mode", "query"))
+        if mode == "build":
+            content = json.dumps(self.build(), ensure_ascii=False)
+        elif mode == "explain":
+            content = self.explain(request.query)
+        elif mode == "path":
+            target = str(request.metadata.get("target", "")).strip()
+            if not target:
+                raise ValueError("graph path mode requires metadata.target")
+            content = self.path(request.query, target)
+        else:
+            content = self.query(request.query)
+        tokens = max(1, len(content) // 4) if content else 0
+        return EngineResult(
+            capability=self.capability,
+            content=content,
+            chunks=[
+                ContextChunk(
+                    source="repository-graph",
+                    content=content,
+                    tokens=tokens,
+                    relevance=0.95,
+                    metadata={"backend": self.spec.key, "revision": self.spec.revision},
+                )
+            ]
+            if content
+            else [],
+            metadata={"backend": self.spec.key, "revision": self.spec.revision},
+        )

codecortex/backends/manager.py

@@ -0,0 +1,303 @@
+"""Isolated lifecycle management for configurable backend engines."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+import venv
+from collections.abc import Mapping, Sequence
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from codecortex.backends.spec import BackendSpec
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessResult:
+    argv: tuple[str, ...]
+    returncode: int
+    stdout: str
+    stderr: str
+    duration_ms: float
+
+
+class BackendProcessError(RuntimeError):
+    def __init__(self, result: ProcessResult) -> None:
+        self.result = result
+        message = result.stderr.strip() or result.stdout.strip() or "backend process failed"
+        super().__init__(f"{result.argv[0]} exited with {result.returncode}: {message[:500]}")
+
+
+def _default_cache_root() -> Path:
+    configured = os.getenv("CODECORTEX_BACKEND_HOME")
+    if configured:
+        return Path(configured).expanduser().resolve()
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Caches" / "codecortex" / "backends"
+    if os.name == "nt":
+        base = Path(os.getenv("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+        return base / "CodeCortex" / "backends"
+    return Path(os.getenv("XDG_CACHE_HOME", Path.home() / ".cache")) / "codecortex" / "backends"
+
+
+def _discover_source_root() -> Path | None:
+    configured = os.getenv("CODECORTEX_SOURCE_ROOT")
+    if configured:
+        candidate = Path(configured).expanduser().resolve()
+        return candidate if candidate.is_dir() else None
+    for candidate in Path(__file__).resolve().parents:
+        if (candidate / "pyproject.toml").is_file():
+            return candidate
+    return None
+
+
+class BackendManager:
+    """Provision explicitly configured engines in isolated environments."""
+
+    def __init__(
+        self,
+        cache_root: Path | None = None,
+        timeout_seconds: float = 300.0,
+        health_ttl_seconds: float = 30.0,
+        source_root: Path | None = None,
+    ) -> None:
+        self.cache_root = (cache_root or _default_cache_root()).expanduser().resolve()
+        self.timeout_seconds = timeout_seconds
+        self.health_ttl_seconds = health_ttl_seconds
+        self.source_root = source_root.expanduser().resolve() if source_root else _discover_source_root()
+        self._probe_cache: dict[tuple[str, str], tuple[float, bool]] = {}
+
+    def environment_dir(self, spec: BackendSpec) -> Path:
+        revision = spec.revision[:12] if spec.revision else "unconfigured"
+        return self.cache_root / spec.key / revision
+
+    def metadata_path(self, spec: BackendSpec) -> Path:
+        return self.environment_dir(spec) / ".codecortex-backend.json"
+
+    def python_path(self, spec: BackendSpec) -> Path:
+        env = self.environment_dir(spec)
+        return env / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+
+    def command_path(self, spec: BackendSpec) -> Path:
+        env = self.environment_dir(spec)
+        suffix = ".exe" if os.name == "nt" else ""
+        command = spec.command or "__unconfigured__"
+        return env / ("Scripts" if os.name == "nt" else "bin") / f"{command}{suffix}"
+
+    def local_source_path(self, spec: BackendSpec) -> Path | None:
+        if not spec.configured or self.source_root is None or not spec.vendor_path:
+            return None
+        candidate = (self.source_root / spec.vendor_path).resolve()
+        try:
+            candidate.relative_to(self.source_root)
+        except ValueError:
+            raise RuntimeError(f"backend local path escapes source root: {spec.vendor_path}") from None
+        if not candidate.is_dir() or not (candidate / "pyproject.toml").is_file():
+            return None
+        revision = self._git_revision(candidate)
+        if revision is not None and revision != spec.revision:
+            raise RuntimeError(
+                f"backend revision mismatch for {spec.key}: expected {spec.revision}, found {revision}"
+            )
+        return candidate
+
+    def install_requirement(self, spec: BackendSpec) -> str:
+        if not spec.configured:
+            raise RuntimeError(f"backend {spec.key!r} is not configured")
+        local = self.local_source_path(spec)
+        if local is None:
+            return spec.source_requirement
+        if spec.extras:
+            return f"{spec.package}[{','.join(spec.extras)}] @ {local.as_uri()}"
+        return str(local)
+
+    def installation_metadata(self, spec: BackendSpec) -> dict[str, object] | None:
+        return self._load_metadata(spec)
+
+    def is_installed(self, spec: BackendSpec) -> bool:
+        if not spec.configured:
+            return False
+        metadata = self._load_metadata(spec)
+        if not metadata or metadata.get("revision") != spec.revision or not self.command_path(spec).exists():
+            return False
+        local = self.local_source_path(spec)
+        return local is None or metadata.get("source_kind") == "local"
+
+    def ensure(self, spec: BackendSpec) -> Path:
+        if not spec.configured:
+            raise RuntimeError(f"backend {spec.key!r} is not configured")
+        if self.is_installed(spec):
+            return self.command_path(spec)
+        env_dir = self.environment_dir(spec)
+        env_dir.parent.mkdir(parents=True, exist_ok=True)
+        lock = env_dir.with_suffix(".lock")
+        self._acquire_lock(lock)
+        try:
+            if self.is_installed(spec):
+                return self.command_path(spec)
+            if env_dir.exists():
+                shutil.rmtree(env_dir)
+            self._create_environment(env_dir, spec)
+            local = self.local_source_path(spec)
+            self._install(spec)
+            payload = asdict(spec)
+            payload["installed_at"] = time.time()
+            payload["source_kind"] = "local" if local is not None else "remote"
+            payload["source_path"] = str(local) if local is not None else None
+            self.metadata_path(spec).write_text(
+                json.dumps(payload, indent=2, sort_keys=True) + "\n",
+                encoding="utf-8",
+            )
+            command = self.command_path(spec)
+            if not command.exists():
+                raise RuntimeError(f"backend installed without expected command: {command}")
+            self._probe_cache.pop((spec.key, spec.revision), None)
+            return command
+        except Exception:
+            if env_dir.exists() and not self.is_installed(spec):
+                shutil.rmtree(env_dir, ignore_errors=True)
+            raise
+        finally:
+            self._release_lock(lock)
+
+    def run(
+        self,
+        spec: BackendSpec,
+        args: Sequence[str],
+        *,
+        cwd: Path | None = None,
+        env: Mapping[str, str] | None = None,
+        timeout_seconds: float | None = None,
+        check: bool = True,
+        provision: bool = True,
+    ) -> ProcessResult:
+        command = self.ensure(spec) if provision else self.command_path(spec)
+        if not command.exists():
+            raise FileNotFoundError(command)
+        argv = (str(command), *(str(item) for item in args))
+        started = time.perf_counter()
+        process = subprocess.run(
+            argv,
+            cwd=str(cwd) if cwd else None,
+            env={**os.environ, **dict(env or {})},
+            text=True,
+            capture_output=True,
+            timeout=timeout_seconds or self.timeout_seconds,
+            check=False,
+        )
+        result = ProcessResult(
+            argv,
+            process.returncode,
+            process.stdout,
+            process.stderr,
+            (time.perf_counter() - started) * 1000,
+        )
+        if check and result.returncode != 0:
+            raise BackendProcessError(result)
+        return result
+
+    def probe(self, spec: BackendSpec, provision: bool = False, *, force: bool = False) -> bool:
+        if not spec.configured:
+            return False
+        key = (spec.key, spec.revision)
+        now = time.monotonic()
+        cached = self._probe_cache.get(key)
+        if not force and cached is not None and now - cached[0] <= self.health_ttl_seconds:
+            return cached[1]
+        try:
+            if not provision and not self.is_installed(spec):
+                healthy = False
+            else:
+                result = self.run(
+                    spec,
+                    ("--help",),
+                    timeout_seconds=30,
+                    provision=provision,
+                    check=False,
+                )
+                healthy = result.returncode == 0
+        except (OSError, RuntimeError, subprocess.SubprocessError):
+            healthy = False
+        self._probe_cache[key] = (now, healthy)
+        return healthy
+
+    def remove(self, spec: BackendSpec) -> None:
+        shutil.rmtree(self.environment_dir(spec), ignore_errors=True)
+        self._probe_cache.pop((spec.key, spec.revision), None)
+
+    def _create_environment(self, env_dir: Path, spec: BackendSpec) -> None:
+        uv = shutil.which("uv")
+        if uv:
+            result = subprocess.run(
+                [uv, "venv", "--python", spec.python, str(env_dir)],
+                text=True,
+                capture_output=True,
+                timeout=self.timeout_seconds,
+                check=False,
+            )
+            if result.returncode == 0:
+                return
+        venv.EnvBuilder(with_pip=True, clear=True).create(env_dir)
+
+    def _install(self, spec: BackendSpec) -> None:
+        python = self.python_path(spec)
+        requirement = self.install_requirement(spec)
+        uv = shutil.which("uv")
+        argv = (
+            [uv, "pip", "install", "--python", str(python), requirement]
+            if uv
+            else [str(python), "-m", "pip", "install", requirement]
+        )
+        process = subprocess.run(
+            argv,
+            text=True,
+            capture_output=True,
+            timeout=self.timeout_seconds,
+            check=False,
+        )
+        if process.returncode != 0:
+            raise RuntimeError(process.stderr.strip() or process.stdout.strip())
+
+    def _load_metadata(self, spec: BackendSpec) -> dict[str, object] | None:
+        try:
+            value = json.loads(self.metadata_path(spec).read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return None
+        return value if isinstance(value, dict) else None
+
+    @staticmethod
+    def _git_revision(path: Path) -> str | None:
+        try:
+            process = subprocess.run(
+                ["git", "-C", str(path), "rev-parse", "HEAD"],
+                text=True,
+                capture_output=True,
+                timeout=10,
+                check=False,
+            )
+        except (OSError, subprocess.SubprocessError):
+            return None
+        revision = process.stdout.strip()
+        return revision if process.returncode == 0 and len(revision) == 40 else None
+
+    def _acquire_lock(self, lock: Path) -> None:
+        deadline = time.monotonic() + min(self.timeout_seconds, 120.0)
+        while True:
+            try:
+                lock.mkdir(parents=False)
+                return
+            except FileExistsError:
+                if time.monotonic() >= deadline:
+                    raise TimeoutError(f"timed out waiting for backend lock: {lock}") from None
+                time.sleep(0.1)
+
+    @staticmethod
+    def _release_lock(lock: Path) -> None:
+        try:
+            lock.rmdir()
+        except OSError:
+            pass

codecortex/backends/mcp_client.py

@@ -0,0 +1,196 @@
+"""Small synchronous MCP stdio client used by isolated backend adapters."""
+
+from __future__ import annotations
+
+import json
+import os
+import queue
+import subprocess
+import threading
+import time
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from codecortex.backends.manager import BackendManager
+from codecortex.backends.spec import BackendSpec
+
+
+class MCPError(RuntimeError):
+    pass
+
+
+class MCPStdioClient:
+    """Persistent JSON-RPC client for an MCP server using stdio transport."""
+
+    def __init__(
+        self,
+        manager: BackendManager,
+        spec: BackendSpec,
+        server_args: Sequence[str],
+        *,
+        cwd: Path | None = None,
+        env: Mapping[str, str] | None = None,
+        timeout_seconds: float = 60.0,
+    ) -> None:
+        self.manager = manager
+        self.spec = spec
+        self.server_args = tuple(server_args)
+        self.cwd = cwd
+        self.env = dict(env or {})
+        self.timeout_seconds = timeout_seconds
+        self._process: subprocess.Popen[str] | None = None
+        self._messages: queue.Queue[dict[str, Any]] = queue.Queue()
+        self._stderr: queue.Queue[str] = queue.Queue()
+        self._request_id = 0
+        self._reader: threading.Thread | None = None
+        self._stderr_reader: threading.Thread | None = None
+
+    def __enter__(self) -> MCPStdioClient:
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:  # noqa: ANN001
+        self.close()
+
+    def start(self) -> None:
+        if self._process is not None:
+            return
+        command = self.manager.ensure(self.spec)
+        self._process = subprocess.Popen(
+            [str(command), *self.server_args],
+            cwd=str(self.cwd) if self.cwd else None,
+            env={**os.environ, **self.env},
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            bufsize=1,
+        )
+        self._reader = threading.Thread(target=self._read_stdout, daemon=True)
+        self._stderr_reader = threading.Thread(target=self._read_stderr, daemon=True)
+        self._reader.start()
+        self._stderr_reader.start()
+        self._initialize()
+
+    def close(self) -> None:
+        process = self._process
+        self._process = None
+        if process is None:
+            return
+        if process.poll() is None:
+            process.terminate()
+            try:
+                process.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait(timeout=3)
+
+    def tools(self) -> list[dict[str, Any]]:
+        result = self.request("tools/list", {})
+        tools = result.get("tools", []) if isinstance(result, dict) else []
+        return [item for item in tools if isinstance(item, dict)]
+
+    def call_tool(self, name: str, arguments: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        result = self.request("tools/call", {"name": name, "arguments": dict(arguments or {})})
+        if not isinstance(result, dict):
+            raise MCPError(f"tool {name!r} returned a non-object result")
+        if result.get("isError"):
+            raise MCPError(self._content_text(result) or f"tool {name!r} failed")
+        return result
+
+    def request(self, method: str, params: Mapping[str, Any]) -> Any:
+        self._request_id += 1
+        request_id = self._request_id
+        self._send({"jsonrpc": "2.0", "id": request_id, "method": method, "params": dict(params)})
+        deadline = time.monotonic() + self.timeout_seconds
+        deferred: list[dict[str, Any]] = []
+        try:
+            while time.monotonic() < deadline:
+                self._raise_if_exited()
+                try:
+                    message = self._messages.get(timeout=min(0.25, max(0.01, deadline - time.monotonic())))
+                except queue.Empty:
+                    continue
+                if message.get("id") != request_id:
+                    deferred.append(message)
+                    continue
+                if "error" in message:
+                    raise MCPError(str(message["error"]))
+                return message.get("result")
+            raise TimeoutError(f"MCP request timed out: {method}")
+        finally:
+            for message in deferred:
+                self._messages.put(message)
+
+    @staticmethod
+    def content_text(result: Mapping[str, Any]) -> str:
+        return MCPStdioClient._content_text(result)
+
+    def _initialize(self) -> None:
+        protocol = os.getenv("CODECORTEX_MCP_PROTOCOL", "2025-06-18")
+        self.request(
+            "initialize",
+            {
+                "protocolVersion": protocol,
+                "capabilities": {},
+                "clientInfo": {"name": "CodeCortex", "version": "0.1.0"},
+            },
+        )
+        self._send({"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}})
+
+    def _send(self, payload: Mapping[str, Any]) -> None:
+        process = self._process
+        if process is None or process.stdin is None:
+            raise MCPError("MCP process is not running")
+        process.stdin.write(json.dumps(payload, separators=(",", ":"), ensure_ascii=False) + "\n")
+        process.stdin.flush()
+
+    def _read_stdout(self) -> None:
+        process = self._process
+        if process is None or process.stdout is None:
+            return
+        for raw in process.stdout:
+            line = raw.strip()
+            if not line:
+                continue
+            try:
+                message = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(message, dict):
+                self._messages.put(message)
+
+    def _read_stderr(self) -> None:
+        process = self._process
+        if process is None or process.stderr is None:
+            return
+        for raw in process.stderr:
+            if raw.strip():
+                self._stderr.put(raw.rstrip())
+
+    def _raise_if_exited(self) -> None:
+        process = self._process
+        if process is None:
+            raise MCPError("MCP process is not running")
+        code = process.poll()
+        if code is None:
+            return
+        lines: list[str] = []
+        while not self._stderr.empty() and len(lines) < 20:
+            lines.append(self._stderr.get_nowait())
+        detail = "\n".join(lines)
+        raise MCPError(f"MCP server exited with {code}: {detail}".strip())
+
+    @staticmethod
+    def _content_text(result: Mapping[str, Any]) -> str:
+        chunks = result.get("content", [])
+        texts: list[str] = []
+        if isinstance(chunks, list):
+            for chunk in chunks:
+                if isinstance(chunk, dict) and chunk.get("type") == "text":
+                    text = chunk.get("text")
+                    if isinstance(text, str):
+                        texts.append(text)
+        return "\n".join(texts)