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

codecortex/evaluation/regression.py

@@ -0,0 +1,188 @@
+"""Persistent benchmark history and deterministic regression gates."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class BenchmarkSnapshot:
+    id: str
+    created_at: str
+    commit: str | None
+    metrics: dict[str, dict[str, float]]
+    metadata: dict[str, str]
+
+
+@dataclass(frozen=True, slots=True)
+class MetricPolicy:
+    metric: str
+    direction: str
+    max_relative_regression: float | None = None
+    max_absolute_regression: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.direction not in {"higher", "lower"}:
+            raise ValueError("direction must be 'higher' or 'lower'")
+
+
+@dataclass(frozen=True, slots=True)
+class RegressionViolation:
+    strategy: str
+    metric: str
+    baseline: float
+    current: float
+    relative_change: float | None
+    absolute_change: float
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class GateReport:
+    passed: bool
+    violations: tuple[RegressionViolation, ...]
+    compared_metrics: int
+
+
+class BenchmarkHistory:
+    VERSION = 1
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    def append(
+        self,
+        metrics: dict[str, dict[str, float]],
+        commit: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> BenchmarkSnapshot:
+        created = datetime.now(UTC).isoformat()
+        snapshot = BenchmarkSnapshot(
+            id=f"bench-{created.replace(':', '').replace('+', '-')}",
+            created_at=created,
+            commit=commit,
+            metrics=metrics,
+            metadata=metadata or {},
+        )
+        snapshots = self.load()
+        snapshots.append(snapshot)
+        self._save(snapshots)
+        return snapshot
+
+    def load(self) -> list[BenchmarkSnapshot]:
+        try:
+            payload = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return []
+        if payload.get("version") != self.VERSION:
+            return []
+        result: list[BenchmarkSnapshot] = []
+        for item in payload.get("snapshots", []):
+            try:
+                result.append(
+                    BenchmarkSnapshot(
+                        id=str(item["id"]),
+                        created_at=str(item["created_at"]),
+                        commit=str(item["commit"]) if item.get("commit") else None,
+                        metrics={
+                            str(strategy): {
+                                str(metric): float(value)
+                                for metric, value in values.items()
+                            }
+                            for strategy, values in item["metrics"].items()
+                        },
+                        metadata={str(key): str(value) for key, value in item.get("metadata", {}).items()},
+                    )
+                )
+            except (KeyError, TypeError, ValueError):
+                continue
+        return result
+
+    def latest(self) -> BenchmarkSnapshot | None:
+        snapshots = self.load()
+        return snapshots[-1] if snapshots else None
+
+    def _save(self, snapshots: list[BenchmarkSnapshot]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "version": self.VERSION,
+            "snapshots": [asdict(snapshot) for snapshot in snapshots],
+        }
+        temp = self.path.with_suffix(self.path.suffix + ".tmp")
+        temp.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+        temp.replace(self.path)
+
+
+class RegressionGate:
+    DEFAULT_POLICIES = (
+        MetricPolicy("success_rate", "higher", max_absolute_regression=0.02),
+        MetricPolicy("avg_path_recall", "higher", max_absolute_regression=0.03),
+        MetricPolicy("avg_symbol_recall", "higher", max_absolute_regression=0.03),
+        MetricPolicy("avg_duration_ms", "lower", max_relative_regression=0.20),
+        MetricPolicy("avg_context_tokens", "lower", max_relative_regression=0.10),
+        MetricPolicy("avg_files_read", "lower", max_relative_regression=0.15),
+        MetricPolicy("avg_tool_calls", "lower", max_relative_regression=0.15),
+    )
+
+    def __init__(self, policies: tuple[MetricPolicy, ...] | None = None) -> None:
+        self.policies = policies or self.DEFAULT_POLICIES
+
+    def evaluate(
+        self,
+        current: BenchmarkSnapshot,
+        baseline: BenchmarkSnapshot,
+    ) -> GateReport:
+        violations: list[RegressionViolation] = []
+        compared = 0
+        for strategy, current_metrics in current.metrics.items():
+            baseline_metrics = baseline.metrics.get(strategy)
+            if baseline_metrics is None:
+                continue
+            for policy in self.policies:
+                if policy.metric not in current_metrics or policy.metric not in baseline_metrics:
+                    continue
+                compared += 1
+                now = current_metrics[policy.metric]
+                before = baseline_metrics[policy.metric]
+                absolute = now - before
+                relative = None if before == 0 else absolute / abs(before)
+                regression = before - now if policy.direction == "higher" else now - before
+                if regression <= 0:
+                    continue
+                reasons: list[str] = []
+                if (
+                    policy.max_absolute_regression is not None
+                    and regression > policy.max_absolute_regression
+                ):
+                    reasons.append(
+                        f"absolute regression {regression:.4f} > {policy.max_absolute_regression:.4f}"
+                    )
+                relative_regression = None if before == 0 else regression / abs(before)
+                if (
+                    policy.max_relative_regression is not None
+                    and relative_regression is not None
+                    and relative_regression > policy.max_relative_regression
+                ):
+                    reasons.append(
+                        f"relative regression {relative_regression:.2%} > {policy.max_relative_regression:.2%}"
+                    )
+                if reasons:
+                    violations.append(
+                        RegressionViolation(
+                            strategy=strategy,
+                            metric=policy.metric,
+                            baseline=before,
+                            current=now,
+                            relative_change=relative,
+                            absolute_change=absolute,
+                            reason="; ".join(reasons),
+                        )
+                    )
+        return GateReport(
+            passed=not violations,
+            violations=tuple(violations),
+            compared_metrics=compared,
+        )

codecortex/gateway.py

@@ -0,0 +1,38 @@
+"""Stable application gateway for every external interface."""
+
+from __future__ import annotations
+
+from codecortex.core.contracts import MemoryStore
+from codecortex.core.models import AgentRequest, ExecutionResult, RoutePlan
+from codecortex.engines import EngineRegistry
+from codecortex.orchestrator import Orchestrator
+from codecortex.router import AdaptiveRouter
+
+
+class CodeCortexGateway:
+    def __init__(
+        self,
+        router: AdaptiveRouter,
+        orchestrator: Orchestrator,
+        registry: EngineRegistry,
+        memory: MemoryStore,
+    ) -> None:
+        self.router = router
+        self.orchestrator = orchestrator
+        self.registry = registry
+        self.memory = memory
+
+    def route(self, query: str, project_root: str = ".") -> RoutePlan:
+        return self.router.route(AgentRequest(query=query, project_root=project_root))
+
+    async def query(self, query: str, project_root: str = ".") -> ExecutionResult:
+        return await self.orchestrator.execute(
+            AgentRequest(query=query, project_root=project_root)
+        )
+
+    async def remember(self, key: str, value: str, namespace: str = "project") -> None:
+        await self.memory.put(namespace, key, value)
+
+    async def health(self) -> dict[str, bool]:
+        health = await self.registry.health()
+        return {capability.value: status for capability, status in health.items()}

codecortex/git_intelligence.py

@@ -0,0 +1,252 @@
+"""Repository and symbol history intelligence from local Git metadata."""
+
+from __future__ import annotations
+
+import subprocess
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class FileActivity:
+    path: str
+    changes: int
+
+
+@dataclass(frozen=True, slots=True)
+class CoChange:
+    left: str
+    right: str
+    commits: int
+
+
+@dataclass(frozen=True, slots=True)
+class AuthorActivity:
+    name: str
+    email: str
+    commits: int
+
+
+@dataclass(frozen=True, slots=True)
+class GitReport:
+    commits: int
+    hot_files: tuple[FileActivity, ...]
+    co_changes: tuple[CoChange, ...]
+    authors: tuple[AuthorActivity, ...]
+    recent_files: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class SymbolCommit:
+    sha: str
+    author: str
+    email: str
+    date: str
+    subject: str
+
+
+@dataclass(frozen=True, slots=True)
+class BlameLine:
+    line: int
+    sha: str
+    author: str
+    email: str
+    timestamp: int | None
+    content: str
+
+
+@dataclass(frozen=True, slots=True)
+class SymbolHistory:
+    path: str
+    start_line: int
+    end_line: int
+    commits: tuple[SymbolCommit, ...]
+    blame: tuple[BlameLine, ...]
+    owners: tuple[AuthorActivity, ...]
+
+
+class GitIntelligence:
+    def __init__(self, root: Path, timeout_seconds: float = 15.0) -> None:
+        self.root = root.resolve()
+        self.timeout_seconds = timeout_seconds
+
+    def _git(self, *args: str) -> str:
+        try:
+            result = subprocess.run(
+                ["git", "-C", str(self.root), *args],
+                check=False,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=self.timeout_seconds,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return ""
+        return result.stdout if result.returncode == 0 else ""
+
+    def is_repository(self) -> bool:
+        return self._git("rev-parse", "--is-inside-work-tree").strip() == "true"
+
+    def analyze(self, limit: int = 500) -> GitReport:
+        raw = self._git(
+            "log",
+            f"-n{max(1, limit)}",
+            "--date=iso-strict",
+            "--format=@@%H|%an|%ae|%ad",
+            "--name-only",
+        )
+        if not raw:
+            return GitReport(0, (), (), (), ())
+        file_changes: Counter[str] = Counter()
+        pair_changes: Counter[tuple[str, str]] = Counter()
+        author_changes: Counter[tuple[str, str]] = Counter()
+        recent: list[str] = []
+        current_files: list[str] = []
+        current_author: tuple[str, str] | None = None
+        commits = 0
+
+        def flush() -> None:
+            nonlocal current_files, current_author
+            unique = sorted(set(current_files))
+            file_changes.update(unique)
+            for index, left in enumerate(unique):
+                for right in unique[index + 1 :]:
+                    pair_changes[(left, right)] += 1
+            if current_author is not None:
+                author_changes[current_author] += 1
+            current_files = []
+            current_author = None
+
+        for line in raw.splitlines():
+            if line.startswith("@@"):
+                if commits:
+                    flush()
+                commits += 1
+                parts = line[2:].split("|", 3)
+                if len(parts) >= 3:
+                    current_author = (parts[1], parts[2])
+                continue
+            path = line.strip()
+            if path:
+                current_files.append(path)
+                if path not in recent:
+                    recent.append(path)
+        if commits:
+            flush()
+        return GitReport(
+            commits=commits,
+            hot_files=tuple(FileActivity(path, count) for path, count in file_changes.most_common(30)),
+            co_changes=tuple(
+                CoChange(left, right, count)
+                for (left, right), count in pair_changes.most_common(30)
+            ),
+            authors=tuple(
+                AuthorActivity(name, email, count)
+                for (name, email), count in author_changes.most_common(20)
+            ),
+            recent_files=tuple(recent[:50]),
+        )
+
+    def file_history(self, path: str, limit: int = 30) -> list[dict[str, str]]:
+        raw = self._git(
+            "log",
+            f"-n{max(1, limit)}",
+            "--date=iso-strict",
+            "--format=%H|%an|%ae|%ad|%s",
+            "--",
+            path,
+        )
+        result: list[dict[str, str]] = []
+        for line in raw.splitlines():
+            parts = line.split("|", 4)
+            if len(parts) == 5:
+                result.append(
+                    {
+                        "sha": parts[0],
+                        "author": parts[1],
+                        "email": parts[2],
+                        "date": parts[3],
+                        "subject": parts[4],
+                    }
+                )
+        return result
+
+    def symbol_history(self, path: str, start_line: int, end_line: int) -> SymbolHistory:
+        if start_line < 1 or end_line < start_line:
+            raise ValueError("invalid symbol line range")
+        commits = self._symbol_commits(path, start_line, end_line)
+        blame = self._blame(path, start_line, end_line)
+        ownership: Counter[tuple[str, str]] = Counter(
+            (line.author, line.email) for line in blame if line.author
+        )
+        owners = tuple(
+            AuthorActivity(name, email, count)
+            for (name, email), count in ownership.most_common()
+        )
+        return SymbolHistory(
+            path=path,
+            start_line=start_line,
+            end_line=end_line,
+            commits=tuple(commits),
+            blame=tuple(blame),
+            owners=owners,
+        )
+
+    def _symbol_commits(self, path: str, start_line: int, end_line: int) -> list[SymbolCommit]:
+        raw = self._git(
+            "log",
+            "--date=iso-strict",
+            "--format=@@C@@%H|%an|%ae|%ad|%s",
+            "-L",
+            f"{start_line},{end_line}:{path}",
+        )
+        commits: list[SymbolCommit] = []
+        seen: set[str] = set()
+        for line in raw.splitlines():
+            if not line.startswith("@@C@@"):
+                continue
+            parts = line[5:].split("|", 4)
+            if len(parts) != 5 or parts[0] in seen:
+                continue
+            seen.add(parts[0])
+            commits.append(SymbolCommit(*parts))
+        return commits
+
+    def _blame(self, path: str, start_line: int, end_line: int) -> list[BlameLine]:
+        raw = self._git(
+            "blame",
+            "--line-porcelain",
+            "-L",
+            f"{start_line},{end_line}",
+            "--",
+            path,
+        )
+        result: list[BlameLine] = []
+        current: dict[str, str] = {}
+        current_line = start_line
+        for line in raw.splitlines():
+            if line.startswith("\t"):
+                timestamp = current.get("author-time")
+                result.append(
+                    BlameLine(
+                        line=current_line,
+                        sha=current.get("sha", ""),
+                        author=current.get("author", ""),
+                        email=current.get("author-mail", "").strip("<>"),
+                        timestamp=int(timestamp) if timestamp and timestamp.isdigit() else None,
+                        content=line[1:],
+                    )
+                )
+                current_line += 1
+                current = {}
+                continue
+            parts = line.split(" ", 1)
+            if len(parts) == 2 and len(parts[0]) >= 7 and all(
+                char in "0123456789abcdef^" for char in parts[0].lower()
+            ):
+                current["sha"] = parts[0].lstrip("^")
+            elif len(parts) == 2:
+                current[parts[0]] = parts[1]
+        return result

codecortex/indexing/__init__.py

@@ -0,0 +1,6 @@
+"""Repository indexing and knowledge graph primitives."""
+
+from codecortex.indexing.graph import GraphEdge, GraphNode, ProjectGraph
+from codecortex.indexing.indexer import ProjectIndexer
+
+__all__ = ["GraphEdge", "GraphNode", "ProjectGraph", "ProjectIndexer"]

codecortex/indexing/graph.py

@@ -0,0 +1,78 @@
+"""Typed project knowledge graph."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class GraphNode(BaseModel):
+    id: str
+    kind: str
+    name: str
+    path: str | None = None
+    line: int | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class GraphEdge(BaseModel):
+    source: str
+    target: str
+    kind: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ProjectGraph(BaseModel):
+    nodes: list[GraphNode] = Field(default_factory=list)
+    edges: list[GraphEdge] = Field(default_factory=list)
+
+    @classmethod
+    def load(cls, path: Path) -> ProjectGraph:
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError, ValueError):
+            return cls()
+        try:
+            return cls.model_validate(payload)
+        except ValueError:
+            return cls()
+
+    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(self.model_dump(mode="json"), ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+        temp.replace(path)
+
+    def search(self, query: str, limit: int = 40) -> list[GraphNode]:
+        terms = {
+            term.lower().strip(".,:;()[]{}")
+            for term in query.split()
+            if len(term.strip()) > 2
+        }
+        scored: list[tuple[int, GraphNode]] = []
+        for node in self.nodes:
+            name = node.name.lower()
+            path = (node.path or "").lower()
+            score = sum(
+                5 if term == name else 3 if term in name else 1 if term in path else 0
+                for term in terms
+            )
+            if score:
+                scored.append((score, node))
+        scored.sort(key=lambda item: (-item[0], item[1].kind, item[1].name))
+        return [node for _, node in scored[:limit]]
+
+    def counts(self) -> dict[str, int]:
+        result: dict[str, int] = {}
+        for node in self.nodes:
+            result[node.kind] = result.get(node.kind, 0) + 1
+        return result
+
+    def nodes_for_path(self, path: str) -> list[GraphNode]:
+        return [node for node in self.nodes if node.path == path]

codecortex/indexing/impact.py

@@ -0,0 +1,127 @@
+"""Graph-based change impact analysis."""
+
+from __future__ import annotations
+
+from collections import defaultdict, deque
+from dataclasses import dataclass
+
+from codecortex.indexing.graph import GraphEdge, GraphNode, ProjectGraph
+
+
+@dataclass(frozen=True, slots=True)
+class ImpactItem:
+    node: GraphNode
+    depth: int
+    via: str
+    risk: float
+
+
+@dataclass(frozen=True, slots=True)
+class ImpactReport:
+    target: GraphNode
+    direct: tuple[ImpactItem, ...]
+    indirect: tuple[ImpactItem, ...]
+    affected_tests: tuple[ImpactItem, ...]
+    risk_score: float
+
+    def to_text(self) -> str:
+        lines = [
+            f"Target: {self.target.kind} {self.target.name}",
+            f"Risk score: {self.risk_score:.2f}",
+            f"Direct dependencies: {len(self.direct)}",
+            f"Indirect dependencies: {len(self.indirect)}",
+            f"Affected tests: {len(self.affected_tests)}",
+        ]
+        ranked = sorted(
+            (*self.direct, *self.indirect),
+            key=lambda item: (-item.risk, item.depth, item.node.name),
+        )[:20]
+        if ranked:
+            lines.append("\nHighest risk:")
+            lines.extend(
+                f"- {item.node.name} [{item.via}, depth={item.depth}, risk={item.risk:.2f}]"
+                for item in ranked
+            )
+        return "\n".join(lines)
+
+
+class ImpactAnalyzer:
+    WEIGHTS = {
+        "calls": 1.0,
+        "inherits": 1.0,
+        "implements": 0.9,
+        "imports": 0.7,
+        "contains": 0.35,
+    }
+
+    def __init__(self, graph: ProjectGraph, max_depth: int = 5) -> None:
+        self.graph = graph
+        self.max_depth = max_depth
+        self._nodes = {node.id: node for node in graph.nodes}
+        incoming: dict[str, list[GraphEdge]] = defaultdict(list)
+        for edge in graph.edges:
+            incoming[edge.target].append(edge)
+        self._incoming = incoming
+
+    def _find_target(self, query: str) -> GraphNode:
+        lowered = query.lower()
+        exact = [node for node in self.graph.nodes if node.name.lower() == lowered]
+        if exact:
+            exact.sort(key=lambda node: (node.kind == "file", node.path or ""))
+            return exact[0]
+        matches = self.graph.search(query, limit=1)
+        if not matches:
+            raise ValueError(f"No graph node found for: {query}")
+        return matches[0]
+
+    def analyze(self, query: str) -> ImpactReport:
+        target = self._find_target(query)
+        queue: deque[tuple[str, int, float, str]] = deque()
+        for edge in self._incoming.get(target.id, []):
+            queue.append((edge.source, 1, self.WEIGHTS.get(edge.kind, 0.5), edge.kind))
+
+        seen: dict[str, ImpactItem] = {}
+        while queue:
+            node_id, depth, strength, via = queue.popleft()
+            if depth > self.max_depth or node_id == target.id:
+                continue
+            node = self._nodes.get(node_id)
+            if node is None:
+                continue
+            risk = strength / max(1.0, depth * 0.85)
+            existing = seen.get(node_id)
+            if existing is not None and existing.risk >= risk:
+                continue
+            item = ImpactItem(node=node, depth=depth, via=via, risk=min(1.0, risk))
+            seen[node_id] = item
+            for edge in self._incoming.get(node_id, []):
+                weight = self.WEIGHTS.get(edge.kind, 0.5)
+                queue.append((edge.source, depth + 1, strength * weight, edge.kind))
+
+        items = list(seen.values())
+        direct = tuple(sorted((item for item in items if item.depth == 1), key=self._sort))
+        indirect = tuple(sorted((item for item in items if item.depth > 1), key=self._sort))
+        tests = tuple(item for item in items if self._is_test(item.node))
+        if items:
+            average = sum(item.risk for item in items) / len(items)
+            breadth = min(1.0, len(items) / 25)
+            risk_score = min(1.0, average * 0.7 + breadth * 0.3)
+        else:
+            risk_score = 0.0
+        return ImpactReport(target, direct, indirect, tests, risk_score)
+
+    @staticmethod
+    def _sort(item: ImpactItem) -> tuple[float, int, str]:
+        return (-item.risk, item.depth, item.node.name)
+
+    @staticmethod
+    def _is_test(node: GraphNode) -> bool:
+        path = (node.path or "").lower()
+        name = node.name.lower()
+        return (
+            "/test" in f"/{path}"
+            or "tests/" in path
+            or name.startswith("test_")
+            or name.endswith("test")
+            or name.endswith("tests")
+        )