@pmaddire/gcie 0.1.2

package/context/architecture_slicer.py

@@ -0,0 +1,308 @@
+"""Architecture-driven context slicing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from pathlib import Path
+
+from llm_context.snippet_selector import estimate_tokens
+
+from .architecture_index import load_architecture_index
+
+
+_MISSING_RATIO_FALLBACK = 0.5
+_STOPWORDS = {
+    "for",
+    "and",
+    "the",
+    "with",
+    "from",
+    "this",
+    "that",
+    "into",
+    "onto",
+    "over",
+    "under",
+    "fix",
+    "add",
+    "update",
+    "refactor",
+    "change",
+    "when",
+    "why",
+    "how",
+    "use",
+    "using",
+    "used",
+    "make",
+    "new",
+}
+_ARCH_KEYWORDS = {
+    "fallback",
+    "router",
+    "routing",
+    "context",
+    "slicer",
+    "architecture",
+    "validation",
+    "mode",
+    "confidence",
+}
+
+
+@dataclass
+class ArchitectureSliceResult:
+    query: str
+    snippets: list[dict]
+    confidence: float
+    matched_subsystems: list[dict]
+    missing_files: list[str]
+    error: str | None = None
+
+
+def _tokenize(text: str) -> set[str]:
+    tokens = []
+    for raw in re.split(r"[\s_-]+", text.lower()):
+        token = "".join(ch for ch in raw if ch.isalnum() or ch == "_")
+        if len(token) >= 3:
+            if token not in _STOPWORDS:
+                tokens.append(token)
+    return set(tokens)
+
+
+def _subsystem_blob(subsystem: dict) -> str:
+    parts = [subsystem.get("name", ""), subsystem.get("purpose", ""), subsystem.get("status", "")]
+    for field in (
+        subsystem.get("interfaces", []),
+        subsystem.get("depends_on", []),
+        subsystem.get("used_by", []),
+        subsystem.get("failure_modes", []),
+        subsystem.get("notes", []),
+    ):
+        if field:
+            parts.extend(field)
+    return " ".join(parts)
+
+
+def _score_subsystem(subsystem: dict, query_tokens: set[str]) -> float:
+    if not query_tokens:
+        return 0.0
+    blob = _subsystem_blob(subsystem).lower()
+    matches = sum(1 for token in query_tokens if token in blob)
+    return matches / max(len(query_tokens), 1)
+
+
+def _snippet_from_lines(lines: list[str], max_lines: int) -> str:
+    return "\n".join(lines[:max_lines]).strip()
+
+
+def _collect_snippets(repo_path: Path, files: list[str], max_lines: int = 120) -> tuple[list[dict], list[str]]:
+    snippets: list[dict] = []
+    missing: list[str] = []
+    for rel_path in files:
+        file_path = repo_path / rel_path
+        if not file_path.exists():
+            missing.append(rel_path)
+            continue
+        try:
+            content = file_path.read_text(encoding="utf-8").splitlines()
+        except Exception:
+            missing.append(rel_path)
+            continue
+        snippet = _snippet_from_lines(content, max_lines=max_lines)
+        if snippet:
+            snippets.append(
+                {
+                    "node_id": f"file:{rel_path}",
+                    "score": 1.0,
+                    "content": snippet,
+                }
+            )
+    return snippets, missing
+
+
+def _validate_index(repo_path: Path, index_data: dict) -> tuple[list[dict], list[str], float]:
+    missing: list[str] = []
+    cleaned: list[dict] = []
+    total = 0
+
+    for subsystem in index_data.get("subsystems", []):
+        key_files = subsystem.get("key_files", []) or []
+        total += len(key_files)
+        valid_files: list[str] = []
+        for rel_path in key_files:
+            if (repo_path / rel_path).exists():
+                valid_files.append(rel_path)
+            else:
+                missing.append(rel_path)
+        cleaned.append({**subsystem, "key_files": valid_files})
+
+    if total == 0:
+        return cleaned, missing, 0.0
+
+    missing_ratio = len(missing) / total
+    return cleaned, missing, missing_ratio
+
+
+def _arch_query(query_tokens: set[str]) -> bool:
+    return bool(query_tokens & _ARCH_KEYWORDS)
+
+
+def _rank_core_files(core_files: list[str], query_tokens: set[str]) -> list[str]:
+    weights = {
+        "router": 3,
+        "routing": 3,
+        "fallback": 3,
+        "architecture": 2,
+        "slicer": 2,
+        "validation": 2,
+        "context": 1,
+        "mode": 1,
+        "confidence": 1,
+    }
+    ranked = []
+    for path in core_files:
+        lowered = path.lower()
+        score = 0
+        for key, weight in weights.items():
+            if key in lowered:
+                score += weight
+        if query_tokens:
+            score += sum(1 for token in query_tokens if token in lowered)
+        ranked.append((score, path))
+    ranked.sort(key=lambda item: item[0], reverse=True)
+    return [path for score, path in ranked]
+
+
+def _select_core_files(index_data: dict, query_tokens: set[str]) -> list[str]:
+    core_files = index_data.get("core_infrastructure", []) or []
+    return _rank_core_files(core_files, query_tokens)
+
+
+def slice_with_architecture(repo_path: Path, query: str) -> ArchitectureSliceResult:
+    index_path = repo_path / ".gcie" / "architecture_index.json"
+    index_data = load_architecture_index(index_path)
+    if index_data is None:
+        return ArchitectureSliceResult(
+            query=query,
+            snippets=[],
+            confidence=0.0,
+            matched_subsystems=[],
+            missing_files=[],
+            error="index_missing",
+        )
+
+    subsystems, missing_files, missing_ratio = _validate_index(repo_path, index_data)
+    if not subsystems:
+        return ArchitectureSliceResult(
+            query=query,
+            snippets=[],
+            confidence=0.0,
+            matched_subsystems=[],
+            missing_files=missing_files,
+            error="no_subsystems",
+        )
+
+    if missing_ratio >= _MISSING_RATIO_FALLBACK and missing_files:
+        return ArchitectureSliceResult(
+            query=query,
+            snippets=[],
+            confidence=0.0,
+            matched_subsystems=[],
+            missing_files=missing_files,
+            error="index_missing_files",
+        )
+
+    query_tokens = _tokenize(query)
+    scored = []
+    for subsystem in subsystems:
+        score = _score_subsystem(subsystem, query_tokens)
+        scored.append((score, subsystem))
+
+    scored.sort(key=lambda item: item[0], reverse=True)
+    matched = [(score, subsystem) for score, subsystem in scored if score > 0]
+
+    if not matched:
+        if _arch_query(query_tokens) and index_data.get("core_infrastructure"):
+            core_files = _select_core_files(index_data, query_tokens)
+            snippets, missing = _collect_snippets(repo_path, core_files)
+            missing_files.extend(missing)
+            return ArchitectureSliceResult(
+                query=query,
+                snippets=snippets,
+                confidence=0.25,
+                matched_subsystems=[],
+                missing_files=missing_files,
+                error=None,
+            )
+        return ArchitectureSliceResult(
+            query=query,
+            snippets=[],
+            confidence=0.0,
+            matched_subsystems=[],
+            missing_files=missing_files,
+            error="low_match",
+        )
+
+    top_score = matched[0][0]
+    if missing_ratio > 0:
+        top_score = max(top_score * (1.0 - missing_ratio), 0.0)
+
+    selected_subsystems = [subsystem for score, subsystem in matched[:3]]
+    selected_files: list[str] = []
+    for subsystem in selected_subsystems:
+        selected_files.extend(subsystem.get("key_files", []))
+
+    include_core = False
+    arch_query = _arch_query(query_tokens)
+    if arch_query:
+        include_core = True
+    if arch_query and top_score <= 0.35:
+        include_core = True
+    if arch_query and len(selected_subsystems) <= 1:
+        include_core = True
+
+    core_files = _select_core_files(index_data, query_tokens)
+    if include_core and core_files:
+        selected_files = core_files + selected_files
+
+    snippets, missing = _collect_snippets(repo_path, selected_files)
+    missing_files.extend(missing)
+
+    if include_core and core_files and not snippets:
+        snippets, missing = _collect_snippets(repo_path, core_files)
+        missing_files.extend(missing)
+
+    return ArchitectureSliceResult(
+        query=query,
+        snippets=snippets,
+        confidence=top_score,
+        matched_subsystems=[
+            {"name": subsystem.get("name", ""), "score": score}
+            for score, subsystem in matched[:3]
+        ],
+        missing_files=missing_files,
+        error=None,
+    )
+
+
+def trim_snippets_to_budget(snippets: list[dict], max_total: int) -> list[dict]:
+    out: list[dict] = []
+    used = 0
+    for item in snippets:
+        tokens = estimate_tokens(item.get("content", ""))
+        if used + tokens > max_total:
+            continue
+        out.append(item)
+        used += tokens
+    return out
+
+
+
+
+
+
+
+
+

package/context/context_router.py

@@ -0,0 +1,70 @@
+"""Route context requests between architecture-driven and normal modes."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Callable
+
+from llm_context.snippet_selector import estimate_tokens
+
+from .architecture_bootstrap import ensure_initialized
+from .architecture_slicer import slice_with_architecture, trim_snippets_to_budget
+from .fallback_evaluator import should_fallback
+
+
+NormalRunner = Callable[[], dict]
+
+
+def _total_tokens(snippets: list[dict]) -> int:
+    return sum(estimate_tokens(item.get("content", "")) for item in snippets)
+
+
+def _record_fallback(repo_path: Path, reason: str | None, config: dict) -> None:
+    if reason is None:
+        return
+    config_path = repo_path / ".gcie" / "context_config.json"
+    config["fallback_reason"] = reason
+    try:
+        config_path.write_text(json.dumps(config, indent=2), encoding="utf-8")
+    except Exception:
+        return
+
+
+def route_context(
+    repo: str,
+    query: str,
+    *,
+    intent: str | None,
+    max_total: int,
+    profile: str | None,
+    normal_runner: NormalRunner,
+) -> dict:
+    repo_path = Path(repo)
+    config = ensure_initialized(repo_path)
+
+    if not config.get("architecture_slicer_enabled", True):
+        _record_fallback(repo_path, "architecture_disabled", config)
+        payload = normal_runner()
+        payload["fallback_reason"] = "architecture_disabled"
+        return payload
+
+    arch_result = slice_with_architecture(repo_path, query)
+    fallback, reason = should_fallback(arch_result, config)
+    if fallback:
+        _record_fallback(repo_path, reason, config)
+        payload = normal_runner()
+        payload["fallback_reason"] = reason
+        return payload
+
+    trimmed = trim_snippets_to_budget(arch_result.snippets, max_total)
+    return {
+        "query": arch_result.query,
+        "profile": profile,
+        "mode": "architecture",
+        "intent": intent,
+        "confidence": arch_result.confidence,
+        "matched_subsystems": arch_result.matched_subsystems,
+        "snippets": trimmed,
+        "token_estimate": _total_tokens(trimmed),
+    }

package/context/fallback_evaluator.py

@@ -0,0 +1,21 @@
+"""Evaluate whether to fall back to normal context."""
+
+from __future__ import annotations
+
+from .architecture_slicer import ArchitectureSliceResult
+
+
+def should_fallback(result: ArchitectureSliceResult, config: dict) -> tuple[bool, str | None]:
+    """Decide whether architecture slicing is insufficient."""
+    if result.error:
+        return True, result.error
+
+    if not result.snippets:
+        return True, "no_snippets"
+
+    threshold = float(config.get("confidence_threshold", 0.2))
+    if result.confidence < threshold:
+        if config.get("fallback_to_normal_on_low_confidence", True):
+            return True, "low_confidence"
+
+    return False, None

package/coverage_integration/__init__.py

@@ -0,0 +1 @@
+"""Coverage integration package."""

package/coverage_integration/coverage_loader.py

@@ -0,0 +1,55 @@
+"""Coverage.py JSON report loader."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class CoverageFileRecord:
+    """Coverage record for a single file."""
+
+    path: str
+    executed_lines: tuple[int, ...]
+    missing_lines: tuple[int, ...]
+    percent_covered: float
+    num_statements: int
+    num_branches: int
+    num_partial_branches: int
+
+
+@dataclass(frozen=True, slots=True)
+class CoverageReport:
+    """Loaded coverage report."""
+
+    files: tuple[CoverageFileRecord, ...]
+
+
+def load_coverage_json(path: str | Path) -> CoverageReport:
+    """Load Coverage.py JSON report from disk."""
+    report_path = Path(path)
+    if not report_path.exists():
+        return CoverageReport(files=())
+
+    data = json.loads(report_path.read_text(encoding="utf-8"))
+    files_data = data.get("files", {})
+
+    records: list[CoverageFileRecord] = []
+    for file_path, entry in files_data.items():
+        summary = entry.get("summary", {})
+        records.append(
+            CoverageFileRecord(
+                path=Path(file_path).as_posix(),
+                executed_lines=tuple(entry.get("executed_lines", [])),
+                missing_lines=tuple(entry.get("missing_lines", [])),
+                percent_covered=float(summary.get("percent_covered", 0.0)),
+                num_statements=int(summary.get("num_statements", 0)),
+                num_branches=int(summary.get("num_branches", 0)),
+                num_partial_branches=int(summary.get("num_partial_branches", 0)),
+            )
+        )
+
+    records.sort(key=lambda r: r.path)
+    return CoverageReport(files=tuple(records))

package/debugging/__init__.py

@@ -0,0 +1,12 @@
+"""Debugging package."""
+
+from .bug_localizer import LocalizedBugReport, localize_bug
+from .execution_path_analyzer import ExecutionPath, neighborhood_path, shortest_path_between
+
+__all__ = [
+    "ExecutionPath",
+    "LocalizedBugReport",
+    "localize_bug",
+    "neighborhood_path",
+    "shortest_path_between",
+]

package/debugging/bug_localizer.py

@@ -0,0 +1,81 @@
+"""Bug localization workflow for GCIE debugging queries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import networkx as nx
+
+from retrieval.hybrid_retriever import hybrid_retrieve
+from retrieval.query_parser import parse_query
+
+from .execution_path_analyzer import neighborhood_path
+
+
+@dataclass(frozen=True, slots=True)
+class LocalizedBugReport:
+    query: str
+    target_symbols: tuple[str, ...]
+    relevant_functions: tuple[str, ...]
+    call_chain: tuple[str, ...]
+    variable_modifications: tuple[str, ...]
+    ranked_candidates: tuple[str, ...]
+
+
+def _function_nodes_touching_symbol(graph: nx.DiGraph, symbol: str) -> tuple[str, ...]:
+    out: set[str] = set()
+    needle = symbol.lower()
+
+    for src, dst, attrs in graph.edges(data=True):
+        edge_type = str(attrs.get("type", ""))
+        if edge_type not in {"WRITES", "MODIFIES", "READS"}:
+            continue
+
+        if str(dst).lower() == f"variable:{needle}" and str(src).startswith("function:"):
+            out.add(str(src))
+
+    return tuple(sorted(out))
+
+
+def localize_bug(
+    graph: nx.DiGraph,
+    query: str,
+    *,
+    git_recency_by_node: dict[str, float] | None = None,
+    coverage_risk_by_node: dict[str, float] | None = None,
+) -> LocalizedBugReport:
+    """Localize likely bug sources from a debugging query."""
+    parsed = parse_query(query)
+    symbols = parsed.symbols
+
+    variable_mods: set[str] = set()
+    for symbol in symbols:
+        variable_mods.update(_function_nodes_touching_symbol(graph, symbol))
+
+    hybrid = hybrid_retrieve(
+        graph,
+        query,
+        git_recency_by_node=git_recency_by_node,
+        coverage_risk_by_node=coverage_risk_by_node,
+        max_hops=3,
+        top_k=10,
+    )
+    ranked = tuple(c.node_id for c in hybrid)
+
+    relevant_functions = tuple(
+        node_id for node_id in ranked if node_id.startswith("function:")
+    )
+
+    chain: tuple[str, ...] = ()
+    if relevant_functions:
+        seed = relevant_functions[0]
+        chain = neighborhood_path(graph, seed=seed, hops=2).nodes
+
+    return LocalizedBugReport(
+        query=query,
+        target_symbols=symbols,
+        relevant_functions=relevant_functions,
+        call_chain=chain,
+        variable_modifications=tuple(sorted(variable_mods)),
+        ranked_candidates=ranked,
+    )

package/debugging/execution_path_analyzer.py

@@ -0,0 +1,42 @@
+"""Execution path analysis helpers for debugging output."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import networkx as nx
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionPath:
+    nodes: tuple[str, ...]
+    reason: str
+
+
+def shortest_path_between(graph: nx.DiGraph, source: str, target: str) -> ExecutionPath | None:
+    """Return shortest undirected path between two nodes when available."""
+    try:
+        path = nx.shortest_path(graph.to_undirected(), source=source, target=target)
+        return ExecutionPath(nodes=tuple(path), reason="shortest_undirected_path")
+    except (nx.NetworkXNoPath, nx.NodeNotFound):
+        return None
+
+
+def neighborhood_path(graph: nx.DiGraph, seed: str, hops: int = 2) -> ExecutionPath:
+    """Return bounded BFS neighborhood around a seed node."""
+    seen = {seed}
+    frontier = {seed}
+
+    for _ in range(max(hops, 0)):
+        nxt: set[str] = set()
+        for node in frontier:
+            nxt.update(graph.predecessors(node))
+            nxt.update(graph.successors(node))
+        nxt -= seen
+        if not nxt:
+            break
+        seen.update(nxt)
+        frontier = nxt
+
+    ordered = tuple(sorted(seen))
+    return ExecutionPath(nodes=ordered, reason=f"neighborhood_hops={hops}")

package/embeddings/__init__.py

@@ -0,0 +1,6 @@
+"""Embeddings package."""
+
+from .encoder import TextEncoder
+from .faiss_index import SearchHit, VectorIndex
+
+__all__ = ["SearchHit", "TextEncoder", "VectorIndex"]

package/embeddings/encoder.py

@@ -0,0 +1,45 @@
+"""Embedding encoder with SentenceTransformers fallback."""
+
+from __future__ import annotations
+
+import hashlib
+import math
+from typing import Iterable
+
+
+def _fallback_vector(text: str, dims: int = 64) -> list[float]:
+    vec = [0.0] * dims
+    tokens = text.lower().split()
+    if not tokens:
+        return vec
+
+    for tok in tokens:
+        digest = hashlib.sha256(tok.encode("utf-8")).digest()
+        idx = int.from_bytes(digest[:4], "big") % dims
+        sign = 1.0 if digest[4] % 2 == 0 else -1.0
+        vec[idx] += sign
+
+    norm = math.sqrt(sum(v * v for v in vec)) or 1.0
+    return [v / norm for v in vec]
+
+
+class TextEncoder:
+    """SentenceTransformer-compatible text encoder with deterministic fallback."""
+
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2") -> None:
+        self.model_name = model_name
+        self._model = None
+        try:
+            from sentence_transformers import SentenceTransformer  # type: ignore
+
+            self._model = SentenceTransformer(model_name)
+        except Exception:
+            self._model = None
+
+    def encode(self, texts: Iterable[str]) -> list[list[float]]:
+        values = list(texts)
+        if self._model is not None:
+            vectors = self._model.encode(values, normalize_embeddings=True)
+            return [list(map(float, row)) for row in vectors]
+
+        return [_fallback_vector(text) for text in values]