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

codecortex/__init__.py

@@ -0,0 +1,3 @@
+"""CodeCortex package."""
+
+__version__ = "0.1.0a1"

codecortex/architecture/__init__.py

@@ -0,0 +1,23 @@
+"""Architecture inference and drift analysis."""
+
+from codecortex.architecture.drift import (
+    ArchitectureDriftDetector,
+    ArchitectureDriftReport,
+    ArchitectureFingerprint,
+    DriftFinding,
+)
+from codecortex.architecture.inference import (
+    ArchitectureHypothesis,
+    ArchitectureInferenceEngine,
+    ArchitectureReport,
+)
+
+__all__ = [
+    "ArchitectureDriftDetector",
+    "ArchitectureDriftReport",
+    "ArchitectureFingerprint",
+    "ArchitectureHypothesis",
+    "ArchitectureInferenceEngine",
+    "ArchitectureReport",
+    "DriftFinding",
+]

codecortex/architecture/drift.py

@@ -0,0 +1,182 @@
+"""Architecture fingerprinting and drift detection."""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from dataclasses import asdict, dataclass
+from pathlib import Path, PurePosixPath
+
+from codecortex.architecture.inference import ArchitectureInferenceEngine
+from codecortex.indexing.graph import ProjectGraph
+
+
+@dataclass(frozen=True, slots=True)
+class ArchitectureFingerprint:
+    version: int
+    pattern: str | None
+    confidence: float
+    dependency_counts: dict[str, int]
+    zone_file_counts: dict[str, int]
+    unresolved_ratio: float
+
+    def save(self, path: Path) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temp = path.with_suffix(path.suffix + ".tmp")
+        temp.write_text(json.dumps(asdict(self), indent=2, ensure_ascii=False), encoding="utf-8")
+        temp.replace(path)
+
+    @classmethod
+    def load(cls, path: Path) -> ArchitectureFingerprint | None:
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+            return cls(
+                version=int(payload["version"]),
+                pattern=str(payload["pattern"]) if payload.get("pattern") else None,
+                confidence=float(payload["confidence"]),
+                dependency_counts={str(k): int(v) for k, v in payload["dependency_counts"].items()},
+                zone_file_counts={str(k): int(v) for k, v in payload["zone_file_counts"].items()},
+                unresolved_ratio=float(payload["unresolved_ratio"]),
+            )
+        except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError):
+            return None
+
+
+@dataclass(frozen=True, slots=True)
+class DriftFinding:
+    kind: str
+    severity: str
+    score: float
+    message: str
+    evidence: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ArchitectureDriftReport:
+    drifted: bool
+    score: float
+    findings: tuple[DriftFinding, ...]
+
+
+class ArchitectureDriftDetector:
+    VERSION = 1
+
+    def fingerprint(self, graph: ProjectGraph) -> ArchitectureFingerprint:
+        report = ArchitectureInferenceEngine().analyze(graph)
+        node_map = {node.id: node for node in graph.nodes}
+        dependencies: Counter[str] = Counter()
+        zones: Counter[str] = Counter()
+        unresolved = 0
+        relevant_edges = 0
+        for node in graph.nodes:
+            if node.kind == "file" and node.path:
+                zones[self._zone(node.path)] += 1
+        for edge in graph.edges:
+            if edge.kind not in {"calls", "imports", "inherits", "implements"}:
+                continue
+            relevant_edges += 1
+            source = node_map.get(edge.source)
+            target = node_map.get(edge.target)
+            if target is None or target.kind in {"reference", "module"}:
+                unresolved += 1
+            source_zone = self._zone(source.path) if source and source.path else "external"
+            target_zone = self._zone(target.path) if target and target.path else "external"
+            dependencies[f"{source_zone}->{target_zone}:{edge.kind}"] += 1
+        primary = report.primary
+        return ArchitectureFingerprint(
+            version=self.VERSION,
+            pattern=primary.name if primary else None,
+            confidence=primary.confidence if primary else 0.0,
+            dependency_counts=dict(sorted(dependencies.items())),
+            zone_file_counts=dict(sorted(zones.items())),
+            unresolved_ratio=unresolved / max(1, relevant_edges),
+        )
+
+    def compare(
+        self,
+        baseline: ArchitectureFingerprint,
+        current: ArchitectureFingerprint,
+        dependency_growth_limit: float = 0.75,
+    ) -> ArchitectureDriftReport:
+        findings: list[DriftFinding] = []
+        if baseline.pattern and current.pattern and baseline.pattern != current.pattern:
+            findings.append(
+                DriftFinding(
+                    "primary-pattern-change",
+                    "high",
+                    0.90,
+                    f"Primary architecture changed from {baseline.pattern} to {current.pattern}.",
+                    (f"baseline={baseline.confidence:.2f}", f"current={current.confidence:.2f}"),
+                )
+            )
+        elif baseline.confidence - current.confidence >= 0.20:
+            findings.append(
+                DriftFinding(
+                    "pattern-confidence-drop",
+                    "medium",
+                    0.55,
+                    "Architecture pattern confidence dropped materially.",
+                    (f"{baseline.confidence:.2f}->{current.confidence:.2f}",),
+                )
+            )
+
+        for signature, count in current.dependency_counts.items():
+            before = baseline.dependency_counts.get(signature, 0)
+            if before == 0 and count > 0:
+                severity = "high" if any(kind in signature for kind in (":calls", ":inherits")) else "medium"
+                findings.append(
+                    DriftFinding(
+                        "new-dependency-direction",
+                        severity,
+                        0.70 if severity == "high" else 0.45,
+                        f"New dependency direction detected: {signature}.",
+                        (f"count={count}",),
+                    )
+                )
+                continue
+            growth = (count - before) / max(1, before)
+            if count - before >= 2 and growth > dependency_growth_limit:
+                findings.append(
+                    DriftFinding(
+                        "dependency-growth",
+                        "medium",
+                        min(0.70, 0.35 + growth * 0.20),
+                        f"Dependency volume increased sharply: {signature}.",
+                        (f"{before}->{count}", f"growth={growth:.0%}"),
+                    )
+                )
+
+        unresolved_delta = current.unresolved_ratio - baseline.unresolved_ratio
+        if unresolved_delta >= 0.12:
+            findings.append(
+                DriftFinding(
+                    "resolution-quality-drop",
+                    "medium",
+                    min(0.65, 0.40 + unresolved_delta),
+                    "Unresolved dependency ratio increased.",
+                    (
+                        f"{baseline.unresolved_ratio:.2%}->{current.unresolved_ratio:.2%}",
+                    ),
+                )
+            )
+
+        score = 1.0
+        for finding in findings:
+            score *= 1.0 - min(0.95, finding.score)
+        aggregate = round(1.0 - score, 4)
+        findings.sort(key=lambda item: (-item.score, item.kind))
+        return ArchitectureDriftReport(
+            drifted=bool(findings),
+            score=aggregate,
+            findings=tuple(findings),
+        )
+
+    @staticmethod
+    def _zone(path: str) -> str:
+        parts = PurePosixPath(path).parts
+        ignored = {"src", "lib", "app", "source"}
+        for part in parts[:-1]:
+            normalized = part.lower().replace("-", "_")
+            if normalized not in ignored:
+                return normalized
+        return "root"

codecortex/architecture/inference.py

@@ -0,0 +1,160 @@
+"""Evidence-based architecture pattern inference with calibrated confidence."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from codecortex.indexing.graph import ProjectGraph
+
+
+@dataclass(frozen=True, slots=True)
+class ArchitectureHypothesis:
+    name: str
+    confidence: float
+    evidence: tuple[str, ...]
+    missing_signals: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ArchitectureReport:
+    primary: ArchitectureHypothesis | None
+    alternatives: tuple[ArchitectureHypothesis, ...]
+    analyzed_files: int
+    analyzed_symbols: int
+
+
+@dataclass(frozen=True, slots=True)
+class _Pattern:
+    name: str
+    groups: tuple[tuple[str, tuple[str, ...], float], ...]
+
+
+class ArchitectureInferenceEngine:
+    """Infer architecture from path vocabulary, symbols, and graph relations.
+
+    Confidence is evidence-derived rather than a binary label. A pattern only reaches
+    high confidence when independent signal groups are present across the repository.
+    """
+
+    _PATTERNS = (
+        _Pattern(
+            "hexagonal",
+            (
+                ("domain", ("domain", "entities", "aggregate"), 0.24),
+                ("ports", ("ports", "port", "interfaces"), 0.24),
+                ("adapters", ("adapters", "adapter"), 0.22),
+                ("application", ("application", "usecases", "use_cases"), 0.18),
+                ("infrastructure", ("infrastructure", "infra"), 0.12),
+            ),
+        ),
+        _Pattern(
+            "clean-architecture",
+            (
+                ("domain", ("domain", "entities"), 0.25),
+                ("use-cases", ("usecases", "use_cases", "application"), 0.25),
+                ("interfaces", ("interfaces", "presenters", "controllers"), 0.20),
+                ("infrastructure", ("infrastructure", "frameworks", "drivers"), 0.20),
+                ("dependency-boundaries", ("repository", "gateway"), 0.10),
+            ),
+        ),
+        _Pattern(
+            "layered",
+            (
+                ("presentation", ("controllers", "controller", "api", "routes"), 0.22),
+                ("service", ("services", "service"), 0.24),
+                ("persistence", ("repositories", "repository", "dao"), 0.24),
+                ("model", ("models", "model", "entities"), 0.16),
+                ("configuration", ("config", "configuration"), 0.14),
+            ),
+        ),
+        _Pattern(
+            "mvc",
+            (
+                ("models", ("models", "model"), 0.34),
+                ("views", ("views", "templates", "view"), 0.33),
+                ("controllers", ("controllers", "controller"), 0.33),
+            ),
+        ),
+        _Pattern(
+            "service-repository",
+            (
+                ("services", ("services", "service"), 0.38),
+                ("repositories", ("repositories", "repository"), 0.38),
+                ("models", ("models", "entities", "model"), 0.14),
+                ("contracts", ("protocol", "interface", "contracts"), 0.10),
+            ),
+        ),
+        _Pattern(
+            "monorepo",
+            (
+                ("apps", ("apps", "applications"), 0.30),
+                ("packages", ("packages", "libs", "libraries"), 0.30),
+                ("workspace", ("workspace", "workspaces"), 0.15),
+                ("shared", ("shared", "common"), 0.15),
+                ("tooling", ("tools", "tooling"), 0.10),
+            ),
+        ),
+        _Pattern(
+            "plugin-oriented",
+            (
+                ("plugins", ("plugins", "plugin", "extensions"), 0.42),
+                ("adapters", ("adapters", "providers"), 0.22),
+                ("registry", ("registry", "registries"), 0.18),
+                ("hooks", ("hooks", "hook"), 0.18),
+            ),
+        ),
+    )
+
+    def analyze(self, graph: ProjectGraph, threshold: float = 0.20) -> ArchitectureReport:
+        corpus = self._corpus(graph)
+        hypotheses = [self._score(pattern, corpus) for pattern in self._PATTERNS]
+        hypotheses = [item for item in hypotheses if item.confidence >= threshold]
+        hypotheses.sort(key=lambda item: (-item.confidence, item.name))
+        return ArchitectureReport(
+            primary=hypotheses[0] if hypotheses else None,
+            alternatives=tuple(hypotheses[1:4]),
+            analyzed_files=sum(1 for node in graph.nodes if node.kind == "file"),
+            analyzed_symbols=sum(
+                1 for node in graph.nodes if node.kind not in {"file", "module", "reference"}
+            ),
+        )
+
+    @staticmethod
+    def _corpus(graph: ProjectGraph) -> set[str]:
+        terms: set[str] = set()
+        for node in graph.nodes:
+            if node.path:
+                path = PurePosixPath(node.path)
+                for part in path.parts:
+                    stem = PurePosixPath(part).stem.lower().replace("-", "_")
+                    terms.add(stem)
+                    terms.update(piece for piece in stem.split("_") if piece)
+            name = node.name.lower().replace("-", "_")
+            terms.add(name)
+            terms.update(piece for piece in name.split("_") if piece)
+        return terms
+
+    @staticmethod
+    def _score(pattern: _Pattern, corpus: set[str]) -> ArchitectureHypothesis:
+        confidence = 0.0
+        evidence: list[str] = []
+        missing: list[str] = []
+        matched_groups = 0
+        for label, aliases, weight in pattern.groups:
+            matches = sorted(alias for alias in aliases if alias in corpus)
+            if matches:
+                confidence += weight
+                matched_groups += 1
+                evidence.append(f"{label}: {', '.join(matches[:3])}")
+            else:
+                missing.append(label)
+        # Independent groups matter more than repeated vocabulary from one layer.
+        diversity = matched_groups / max(1, len(pattern.groups))
+        confidence *= 0.70 + 0.30 * diversity
+        return ArchitectureHypothesis(
+            name=pattern.name,
+            confidence=round(min(1.0, confidence), 4),
+            evidence=tuple(evidence),
+            missing_signals=tuple(missing),
+        )

codecortex/backends/__init__.py

@@ -0,0 +1,35 @@
+"""Stable optional backend boundary."""
+
+from codecortex.backends.context import ContextBackendAdapter
+from codecortex.backends.contracts import (
+    BackendCompatibilityError,
+    BackendStatus,
+    ContextIntelligence,
+    GraphIntelligence,
+    ManagedBackend,
+    SymbolIntelligence,
+)
+from codecortex.backends.graph import GraphBackendAdapter
+from codecortex.backends.manager import BackendManager, BackendProcessError, ProcessResult
+from codecortex.backends.mcp_client import MCPError, MCPStdioClient
+from codecortex.backends.spec import BACKENDS, BackendSpec
+from codecortex.backends.symbols import SymbolBackendAdapter
+
+__all__ = [
+    "BACKENDS",
+    "BackendCompatibilityError",
+    "BackendManager",
+    "BackendProcessError",
+    "BackendSpec",
+    "BackendStatus",
+    "ContextBackendAdapter",
+    "ContextIntelligence",
+    "GraphBackendAdapter",
+    "GraphIntelligence",
+    "MCPError",
+    "MCPStdioClient",
+    "ManagedBackend",
+    "ProcessResult",
+    "SymbolBackendAdapter",
+    "SymbolIntelligence",
+]

codecortex/backends/base.py

@@ -0,0 +1,38 @@
+"""Common adapter behavior and compatibility reporting."""
+
+from __future__ import annotations
+
+from codecortex.backends.contracts import BackendCompatibilityError, BackendStatus
+from codecortex.backends.manager import BackendManager
+from codecortex.backends.spec import BackendSpec
+
+
+class ManagedAdapterMixin:
+    contract_version = 1
+    manager: BackendManager
+    spec: BackendSpec
+
+    def status(self) -> BackendStatus:
+        installed = self.manager.is_installed(self.spec)
+        healthy = self.manager.probe(self.spec, provision=False) if installed else False
+        return BackendStatus(
+            key=self.spec.key,
+            installed=installed,
+            healthy=healthy,
+            revision=self.spec.revision,
+            contract_version=self.contract_version,
+            capabilities=self.spec.capabilities,
+        )
+
+    @staticmethod
+    def require_tools(catalog: list[dict[str, object]], required: set[str]) -> None:
+        available = {
+            str(item.get("name"))
+            for item in catalog
+            if isinstance(item.get("name"), str)
+        }
+        missing = sorted(required - available)
+        if missing:
+            raise BackendCompatibilityError(
+                "backend tool contract mismatch; missing: " + ", ".join(missing)
+            )

codecortex/backends/context.py

@@ -0,0 +1,118 @@
+"""Configurable context-processing backend adapter."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Mapping, Sequence
+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
+
+
+class ContextBackendAdapter(ManagedAdapterMixin, Engine):
+    capability = Capability.CONTEXT
+    required_tools = {"context_compress", "context_retrieve", "context_stats"}
+
+    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["context"]
+        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 ("mcp", "serve", "--transport", "stdio")
+
+    def _env(self) -> dict[str, str]:
+        workspace = self.project_root / ".codecortex" / "context-backend"
+        workspace.mkdir(parents=True, exist_ok=True)
+        return {"CODECORTEX_CONTEXT_WORKSPACE_DIR": str(workspace)}
+
+    def _client(self) -> MCPStdioClient:
+        return MCPStdioClient(
+            self.manager,
+            self.spec,
+            self.server_args(),
+            cwd=self.project_root,
+            env=self._env(),
+        )
+
+    def tools(self) -> list[dict[str, Any]]:
+        tools = self.pool.tools(
+            self.spec,
+            self.server_args(),
+            cwd=self.project_root,
+            env=self._env(),
+        )
+        self.require_tools(tools, self.required_tools)
+        return tools
+
+    def compress(self, content: str) -> dict[str, Any]:
+        return self.call("context_compress", {"content": content})
+
+    def compress_batch(self, contents: Sequence[str]) -> list[dict[str, Any]]:
+        return [self.compress(content) for content in contents]
+
+    def retrieve(self, hash_key: str) -> dict[str, Any]:
+        return self.call("context_retrieve", {"hash": hash_key})
+
+    def stats(self) -> dict[str, Any]:
+        return self.call("context_stats", {})
+
+    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,
+            env=self._env(),
+        )
+
+    async def execute(self, request: AgentRequest) -> EngineResult:
+        return await asyncio.to_thread(self._execute_sync, request)
+
+    def _execute_sync(self, request: AgentRequest) -> EngineResult:
+        tool = request.metadata.get("context_tool")
+        arguments = request.metadata.get("context_arguments")
+        payload = (
+            self.call(tool, dict(arguments) if isinstance(arguments, Mapping) else {})
+            if isinstance(tool, str)
+            else self.compress(request.query)
+        )
+        tool = tool if isinstance(tool, str) else "context_compress"
+        content = MCPStdioClient.content_text(payload) or json.dumps(payload, ensure_ascii=False)
+        metadata: dict[str, Any] = {
+            "backend": self.spec.key,
+            "revision": self.spec.revision,
+            "tool": tool,
+        }
+        structured = payload.get("structuredContent")
+        if isinstance(structured, dict):
+            metadata["compression"] = structured
+        return EngineResult(
+            capability=self.capability,
+            content=content,
+            chunks=[
+                ContextChunk(
+                    source=f"context:{tool}",
+                    content=content,
+                    tokens=max(1, len(content) // 4),
+                    relevance=1.0,
+                    metadata=metadata,
+                )
+            ]
+            if content
+            else [],
+            metadata=metadata,
+        )

codecortex/backends/contracts.py

@@ -0,0 +1,65 @@
+"""Stable CodeCortex-side contracts for optional mature backends.
+
+These interfaces are the compatibility boundary. CodeCortex code outside this
+package must not import backend implementation modules or internal APIs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from codecortex.backends.spec import BackendSpec
+
+
+@dataclass(frozen=True, slots=True)
+class BackendStatus:
+    key: str
+    installed: bool
+    healthy: bool
+    revision: str
+    contract_version: int
+    capabilities: tuple[str, ...]
+    detail: str = ""
+
+
+class BackendCompatibilityError(RuntimeError):
+    pass
+
+
+@runtime_checkable
+class ManagedBackend(Protocol):
+    spec: BackendSpec
+    contract_version: int
+
+    async def health(self) -> bool: ...
+
+    def status(self) -> BackendStatus: ...
+
+
+@runtime_checkable
+class GraphIntelligence(ManagedBackend, Protocol):
+    def build(self) -> dict[str, Any]: ...
+
+    def query(self, query: str) -> str: ...
+
+    def explain(self, node: str) -> str: ...
+
+    def path(self, source: str, target: str) -> str: ...
+
+
+@runtime_checkable
+class SymbolIntelligence(ManagedBackend, Protocol):
+    def tools(self) -> list[dict[str, Any]]: ...
+
+    def call(self, tool: str, arguments: Mapping[str, Any]) -> dict[str, Any]: ...
+
+
+@runtime_checkable
+class ContextIntelligence(ManagedBackend, Protocol):
+    def compress(self, content: str) -> dict[str, Any]: ...
+
+    def retrieve(self, hash_key: str) -> dict[str, Any]: ...
+
+    def stats(self) -> dict[str, Any]: ...

codecortex/backends/factory.py

@@ -0,0 +1,60 @@
+"""Assembly of CodeCortex-owned intelligence with optional configured adapters."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from codecortex.backends.context import ContextBackendAdapter
+from codecortex.backends.graph import GraphBackendAdapter
+from codecortex.backends.manager import BackendManager
+from codecortex.backends.spec import BACKENDS
+from codecortex.backends.symbols import SymbolBackendAdapter
+from codecortex.config import CortexConfig
+from codecortex.context import IntegratedContextProcessor
+from codecortex.core.contracts import ContextProcessor, MemoryStore
+from codecortex.engines import EngineRegistry
+from codecortex.engines.builtin import build_default_registry
+
+
+@dataclass(slots=True)
+class BackendStack:
+    registry: EngineRegistry
+    context_processor: ContextProcessor
+    manager: BackendManager
+    active: tuple[str, ...]
+
+
+def build_backend_stack(config: CortexConfig, memory_store: MemoryStore) -> BackendStack:
+    registry = build_default_registry(config, memory_store=memory_store)
+    manager = BackendManager()
+    mode = os.getenv("CODECORTEX_BACKENDS", "builtin").strip().lower()
+    if mode == "mature":
+        mode = "external"
+    if mode not in {"auto", "builtin", "external"}:
+        mode = "builtin"
+
+    active: list[str] = []
+    context_backend: ContextBackendAdapter | None = None
+    if mode != "builtin":
+        graph = GraphBackendAdapter(config.project_root, manager)
+        symbols = SymbolBackendAdapter(config.project_root, manager)
+        context = ContextBackendAdapter(config.project_root, manager)
+        for key, adapter in (("graph", graph), ("symbols", symbols)):
+            spec = BACKENDS[key]
+            if spec.configured and (mode == "external" or manager.is_installed(spec)):
+                registry.register(adapter)
+                active.append(key)
+        context_spec = BACKENDS["context"]
+        if context_spec.configured and (
+            mode == "external" or manager.is_installed(context_spec)
+        ):
+            context_backend = context
+            active.append("context")
+
+    return BackendStack(
+        registry=registry,
+        context_processor=IntegratedContextProcessor(context_backend),
+        manager=manager,
+        active=tuple(active),
+    )