kernhell 0.1.0__py3-none-any.whl

kernhell/api/server.py

@@ -0,0 +1,367 @@
+"""FastAPI Mission Control Bridge for KernHell.
+
+Provides REST API endpoints for:
+  - Cache telemetry & inspection
+  - Healing history & diff inspection
+  - Live selector healing & scan triggering
+  - Interactive test simulation playground
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+import structlog
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+from kernhell import __version__
+from kernhell.analyzer.analyzer import FailureAnalyzer
+from kernhell.analyzer.healer import SelectorHealer
+from kernhell.cache.cache_manager import CacheManager
+from kernhell.core.config import KernHellConfig, load_config
+from kernhell.core.models import (
+    Diagnosis,
+    FailureContext,
+    FailureType,
+    HealingReport,
+    PrunedDOM,
+    SelectorFix,
+    SelectorStrategy,
+    SelectorType,
+)
+from kernhell.core.orchestrator import HealingOrchestrator
+from kernhell.patcher.patcher import SurgicalPatcher
+from kernhell.pruner.dom_pruner import prune_dom
+
+logger = structlog.get_logger()
+
+# ---------------------------------------------------------------------------
+# API Data Models
+# ---------------------------------------------------------------------------
+
+
+class ScanRequest(BaseModel):
+    test_file: str
+
+
+class HealRequest(BaseModel):
+    test_file: str
+    dry_run: bool = False
+
+
+class SimulateRequest(BaseModel):
+    broken_selector: str
+    dom_html: str
+    surrounding_code: str = ""
+    page_url: str = "https://example.com/checkout"
+
+
+class SimulateResponse(BaseModel):
+    broken_selector: str
+    original_dom_bytes: int
+    pruned_dom_bytes: int
+    compression_percent: float
+    pruned_dom: str
+    diagnosis: Diagnosis
+    healed_selector: Optional[SelectorFix] = None
+    applied_diff: Optional[str] = None
+    from_cache: bool = False
+
+
+# ---------------------------------------------------------------------------
+# History Manager
+# ---------------------------------------------------------------------------
+
+
+class RunHistoryManager:
+    """Stores and retrieves historical healing runs in JSON storage."""
+
+    def __init__(self, storage_dir: Path) -> None:
+        self.history_file = storage_dir / "healing_history.json"
+        self._ensure_file()
+
+    def _ensure_file(self) -> None:
+        if not self.history_file.is_file():
+            self.history_file.write_text("[]", encoding="utf-8")
+
+    def record_run(self, report: HealingReport, diff: str = "") -> None:
+        try:
+            runs = self.get_runs()
+            record = {
+                "test_file": str(report.test_file),
+                "total_failures": report.total_failures,
+                "healed_count": report.healed_count,
+                "skipped_count": report.skipped_count,
+                "cache_hits": report.cache_hits,
+                "llm_calls": report.llm_calls,
+                "verification_passed": report.verification_passed,
+                "duration_ms": report.duration_ms,
+                "diff": diff,
+                "results": [
+                    {
+                        "broken_selector": r.failure.broken_selector,
+                        "line_number": r.failure.line_number,
+                        "healed_selector": r.fix.new_selector if r.fix else None,
+                        "strategy": r.fix.strategy.value if r.fix else None,
+                        "confidence": r.fix.confidence if r.fix else None,
+                        "from_cache": r.from_cache,
+                        "skipped": r.skipped,
+                        "skip_reason": r.skip_reason,
+                    }
+                    for r in report.results
+                ],
+            }
+            runs.insert(0, record)
+            # Cap at 50 recent runs
+            self.history_file.write_text(json.dumps(runs[:50], indent=2), encoding="utf-8")
+        except Exception as exc:
+            logger.warning("history.record_failed", error=str(exc))
+
+    def get_runs(self) -> list[dict[str, Any]]:
+        try:
+            if self.history_file.is_file():
+                return json.loads(self.history_file.read_text(encoding="utf-8"))
+        except Exception:
+            pass
+        return []
+
+
+# ---------------------------------------------------------------------------
+# App Factory
+# ---------------------------------------------------------------------------
+
+
+def create_app(config: Optional[KernHellConfig] = None) -> FastAPI:
+    cfg = config or load_config()
+    cache_path = Path(os.path.expanduser(cfg.cache.cache_dir)).resolve()
+    cache_path.mkdir(parents=True, exist_ok=True)
+
+    cache_mgr = CacheManager(cfg)
+    history_mgr = RunHistoryManager(cache_path)
+    orchestrator = HealingOrchestrator(cfg)
+    analyzer = FailureAnalyzer(cfg)
+    healer = SelectorHealer(cfg)
+    patcher = SurgicalPatcher()
+
+    app = FastAPI(
+        title="KernHell Mission Control API",
+        description="REST bridge for KernHell Autonomous Self-Healing Testing Engine",
+        version=__version__,
+    )
+
+    # Enable CORS for Next.js development and production
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    @app.get("/api/health")
+    def health():
+        return {
+            "status": "healthy",
+            "app": "KernHell Mission Control",
+            "version": __version__,
+        }
+
+    @app.get("/api/stats")
+    def get_stats():
+        cache_stats = cache_mgr.get_stats()
+        runs = history_mgr.get_runs()
+
+        total_heals = sum(r.get("healed_count", 0) for r in runs)
+        total_skipped = sum(r.get("skipped_count", 0) for r in runs)
+
+        # Developer value calculation: avg 25 mins per broken selector debug
+        minutes_saved = total_heals * 25
+        hours_saved = round(minutes_saved / 60.0, 1)
+        dollars_saved = round(hours_saved * 85.0, 2)  # $85/hr QA/dev rate
+
+        return {
+            "total_runs": len(runs),
+            "total_healed": total_heals,
+            "real_bugs_caught": total_skipped,
+            "cache_entries": cache_stats.total_entries,
+            "cache_hits": cache_stats.hits,
+            "cache_misses": cache_stats.misses,
+            "cache_efficiency_pct": cache_stats.hit_ratio,
+            "hours_saved": hours_saved,
+            "dollars_saved": dollars_saved,
+        }
+
+    @app.get("/api/history")
+    def get_history():
+        return history_mgr.get_runs()
+
+    @app.get("/api/cache")
+    def list_cache():
+        entries = cache_mgr.list_entries()
+        return [e.model_dump(mode="json") for e in entries]
+
+    @app.post("/api/cache/clear")
+    def clear_cache():
+        count = cache_mgr.clear()
+        return {"cleared_count": count, "message": "Cache successfully cleared"}
+
+    @app.post("/api/scan")
+    def trigger_scan(req: ScanRequest):
+        target = Path(req.test_file).resolve()
+        if not target.is_file():
+            raise HTTPException(status_code=404, detail=f"File not found: {req.test_file}")
+
+        try:
+            results = orchestrator.scan(target)
+            return {
+                "test_file": str(target),
+                "failures_detected": len(results),
+                "failures": [
+                    {
+                        "broken_selector": f.broken_selector,
+                        "line_number": f.line_number,
+                        "error_type": f.error_type.value,
+                        "selector_type": f.selector_type.value,
+                        "pruned_bytes": p.pruned_size if p else None,
+                        "compression_pct": p.reduction_pct if p else None,
+                    }
+                    for f, p in results
+                ],
+            }
+        except Exception as exc:
+            raise HTTPException(status_code=500, detail=str(exc))
+
+    @app.post("/api/heal")
+    def trigger_heal(req: HealRequest):
+        target = Path(req.test_file).resolve()
+        if not target.is_file():
+            raise HTTPException(status_code=404, detail=f"File not found: {req.test_file}")
+
+        try:
+            report = orchestrator.heal(target, dry_run=req.dry_run)
+            history_mgr.record_run(report)
+            return report.model_dump(mode="json")
+        except Exception as exc:
+            raise HTTPException(status_code=500, detail=str(exc))
+
+    @app.post("/api/simulate", response_model=SimulateResponse)
+    def simulate_playground(req: SimulateRequest):
+        """Interactive Simulation: Prunes DOM, classifies, and heals in real time."""
+        pruned = prune_dom(req.dom_html)
+
+        dummy_ctx = FailureContext(
+            test_file=Path("playground_simulation.py"),
+            line_number=10,
+            broken_selector=req.broken_selector,
+            selector_type=SelectorType.CSS,
+            error_message=f"Timeout waiting for locator('{req.broken_selector}')",
+            live_dom=req.dom_html,
+            page_url=req.page_url,
+            surrounding_code=req.surrounding_code or f'page.click("{req.broken_selector}")',
+        )
+
+        # 1. Check cache first
+        cached_fix, score = cache_mgr.lookup(
+            req.broken_selector,
+            context=dummy_ctx.surrounding_code,
+            page_url=req.page_url,
+        )
+
+        if cached_fix:
+            diff_text = None
+            if req.surrounding_code:
+                try:
+                    patched = patcher.apply_patch(
+                        req.surrounding_code,
+                        req.broken_selector,
+                        cached_fix.new_selector,
+                    )
+                    import difflib
+
+                    diff_lines = list(
+                        difflib.unified_diff(
+                            req.surrounding_code.splitlines(),
+                            patched.splitlines(),
+                            fromfile="broken_code.py",
+                            tofile="healed_code.py",
+                            lineterm="",
+                        )
+                    )
+                    diff_text = "\n".join(diff_lines)
+                except Exception:
+                    pass
+
+            return SimulateResponse(
+                broken_selector=req.broken_selector,
+                original_dom_bytes=pruned.original_size,
+                pruned_dom_bytes=pruned.pruned_size,
+                compression_percent=pruned.reduction_pct,
+                pruned_dom=pruned.html,
+                diagnosis=Diagnosis(
+                    failure_type=FailureType.RENAME,
+                    explanation=f"Found verified fix in Semantic Memory with {int(score * 100)}% cosine similarity.",
+                    confidence=score,
+                ),
+                healed_selector=cached_fix,
+                applied_diff=diff_text,
+                from_cache=True,
+            )
+
+        # 2. AI Failure Diagnosis
+        diagnosis = analyzer.diagnose(dummy_ctx, pruned)
+
+        fix: Optional[SelectorFix] = None
+        diff_text = None
+
+        if diagnosis.failure_type != FailureType.MISSING:
+            try:
+                fix = healer.suggest_fix(dummy_ctx, diagnosis, pruned)
+                # Store in cache for future hits
+                cache_mgr.store(
+                    broken_selector=req.broken_selector,
+                    fix=fix,
+                    context=dummy_ctx.surrounding_code,
+                    page_url=req.page_url,
+                )
+                if req.surrounding_code:
+                    try:
+                        patched = patcher.apply_patch(
+                            req.surrounding_code,
+                            req.broken_selector,
+                            fix.new_selector,
+                        )
+                        import difflib
+
+                        diff_lines = list(
+                            difflib.unified_diff(
+                                req.surrounding_code.splitlines(),
+                                patched.splitlines(),
+                                fromfile="broken_code.py",
+                                tofile="healed_code.py",
+                                lineterm="",
+                            )
+                        )
+                        diff_text = "\n".join(diff_lines)
+                    except Exception:
+                        pass
+            except Exception as exc:
+                logger.warning("simulate.healer_failed", error=str(exc))
+
+        return SimulateResponse(
+            broken_selector=req.broken_selector,
+            original_dom_bytes=pruned.original_size,
+            pruned_dom_bytes=pruned.pruned_size,
+            compression_percent=pruned.reduction_pct,
+            pruned_dom=pruned.html,
+            diagnosis=diagnosis,
+            healed_selector=fix,
+            applied_diff=diff_text,
+            from_cache=False,
+        )
+
+    return app

kernhell/cache/__init__.py

@@ -0,0 +1,13 @@
+"""Cache package — Semantic vector memory for selector healing."""
+
+from kernhell.cache.cache_manager import CacheManager
+from kernhell.cache.embedder import SemanticEmbedder, cosine_similarity
+from kernhell.cache.schemas import CacheEntry, CacheStats
+
+__all__ = [
+    "CacheManager",
+    "SemanticEmbedder",
+    "CacheEntry",
+    "CacheStats",
+    "cosine_similarity",
+]

kernhell/cache/cache_manager.py

@@ -0,0 +1,221 @@
+"""Semantic Vector Cache Manager — stores and retrieves verified selector fixes.
+
+When a selector fails, KernHell checks this cache BEFORE calling any LLM.
+If a semantically equivalent selector + context was healed previously,
+it applies the fix with ZERO latency and ZERO LLM cost.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+import structlog
+
+from kernhell.cache.embedder import SemanticEmbedder, cosine_similarity
+from kernhell.cache.schemas import CacheEntry, CacheStats
+from kernhell.core.config import KernHellConfig
+from kernhell.core.models import SelectorFix, SelectorStrategy
+
+logger = structlog.get_logger()
+
+
+class CacheManager:
+    """Manages semantic vector memory and similarity retrieval for healed selectors."""
+
+    def __init__(self, config: KernHellConfig) -> None:
+        self.config = config
+        self.cache_cfg = config.cache
+        self.embedder = SemanticEmbedder(self.cache_cfg.embedding_model)
+
+        # Resolve cache storage directory
+        cache_path = os.path.expanduser(self.cache_cfg.cache_dir)
+        self.storage_dir = Path(cache_path).resolve()
+        self.storage_dir.mkdir(parents=True, exist_ok=True)
+
+        self.db_file = self.storage_dir / "semantic_index.json"
+        self.stats_file = self.storage_dir / "stats.json"
+
+        # In-memory storage: id -> (entry, vector)
+        self._entries: dict[str, CacheEntry] = {}
+        self._vectors: dict[str, list[float]] = {}
+        self._stats = CacheStats()
+
+        self._load()
+
+    def _make_key(self, selector: str, context: str, page_url: str) -> str:
+        """Create a deterministic hash for selector + intent context."""
+        raw = f"{selector.strip()}|{context.strip()}|{page_url.strip()}"
+        return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+    def lookup(
+        self,
+        broken_selector: str,
+        context: str = "",
+        page_url: str = "",
+    ) -> tuple[Optional[SelectorFix], float]:
+        """Look up a selector in semantic memory.
+
+        Returns
+        -------
+        tuple[Optional[SelectorFix], float]
+            (SelectorFix, similarity_score). If similarity < threshold or cache empty,
+            returns (None, score).
+        """
+        if not self.cache_cfg.enabled or not self._entries:
+            self._stats.misses += 1
+            self._save_stats()
+            return None, 0.0
+
+        query_text = f"{broken_selector} | {context} | {page_url}"
+        query_vec = self.embedder.embed(query_text)
+
+        best_score = -1.0
+        best_entry: Optional[CacheEntry] = None
+
+        for entry_id, vec in self._vectors.items():
+            score = cosine_similarity(query_vec, vec)
+            if score > best_score:
+                best_score = score
+                best_entry = self._entries[entry_id]
+
+        threshold = self.cache_cfg.similarity_threshold
+
+        if best_entry is not None and best_score >= threshold:
+            best_entry.hit_count += 1
+            self._stats.hits += 1
+            self._save()
+            logger.info(
+                "cache.hit",
+                broken=broken_selector,
+                healed=best_entry.new_selector,
+                score=round(best_score, 4),
+            )
+            fix = SelectorFix(
+                old_selector=best_entry.broken_selector,
+                new_selector=best_entry.new_selector,
+                strategy=best_entry.strategy,
+                confidence=round(best_entry.confidence, 2),
+                reasoning=f"Retrieved from Semantic Memory (similarity {best_score:.2f} >= {threshold:.2f}).",
+                verified=True,
+            )
+            return fix, best_score
+
+        self._stats.misses += 1
+        self._save_stats()
+        logger.debug(
+            "cache.miss",
+            broken=broken_selector,
+            best_score=round(best_score, 4),
+            threshold=threshold,
+        )
+        return None, best_score
+
+    def store(
+        self,
+        broken_selector: str,
+        fix: SelectorFix,
+        context: str = "",
+        page_url: str = "",
+        test_file: str = "",
+    ) -> CacheEntry:
+        """Store a verified selector fix in semantic memory."""
+        if not self.cache_cfg.enabled:
+            return CacheEntry(
+                id="disabled",
+                broken_selector=broken_selector,
+                new_selector=fix.new_selector,
+                confidence=fix.confidence,
+            )
+
+        entry_id = self._make_key(broken_selector, context, page_url)
+        entry_text = f"{broken_selector} | {context} | {page_url}"
+        vec = self.embedder.embed(entry_text)
+
+        entry = CacheEntry(
+            id=entry_id,
+            broken_selector=broken_selector,
+            new_selector=fix.new_selector,
+            strategy=fix.strategy,
+            confidence=fix.confidence,
+            context_snippet=context[:200] if context else "",
+            page_url=page_url,
+            test_file=test_file,
+            verified=fix.verified,
+        )
+
+        self._entries[entry_id] = entry
+        self._vectors[entry_id] = vec
+        self._stats.total_entries = len(self._entries)
+        self._save()
+
+        logger.info(
+            "cache.stored",
+            broken=broken_selector,
+            healed=fix.new_selector,
+            total_entries=len(self._entries),
+        )
+        return entry
+
+    def list_entries(self) -> list[CacheEntry]:
+        """Return all stored entries in cache."""
+        return list(self._entries.values())
+
+    def clear(self) -> int:
+        """Purge all entries from the vector cache."""
+        count = len(self._entries)
+        self._entries.clear()
+        self._vectors.clear()
+        self._stats = CacheStats()
+        self._save()
+        logger.info("cache.cleared", count=count)
+        return count
+
+    def get_stats(self) -> CacheStats:
+        """Get cache performance metrics."""
+        self._stats.total_entries = len(self._entries)
+        return self._stats
+
+    def _save(self) -> None:
+        """Persist cache entries and vectors to disk."""
+        data = {
+            "entries": {k: v.model_dump(mode="json") for k, v in self._entries.items()},
+            "vectors": self._vectors,
+        }
+        try:
+            self.db_file.write_text(json.dumps(data, indent=2), encoding="utf-8")
+            self._save_stats()
+        except Exception as exc:
+            logger.warning("cache.save_failed", error=str(exc))
+
+    def _save_stats(self) -> None:
+        try:
+            self.stats_file.write_text(
+                self._stats.model_dump_json(indent=2), encoding="utf-8"
+            )
+        except Exception as exc:
+            logger.debug("cache.save_stats_failed", error=str(exc))
+
+    def _load(self) -> None:
+        """Load persisted cache entries and vectors from disk."""
+        if not self.db_file.is_file():
+            return
+
+        try:
+            raw = self.db_file.read_text(encoding="utf-8")
+            data = json.loads(raw)
+            for k, entry_dict in data.get("entries", {}).items():
+                self._entries[k] = CacheEntry.model_validate(entry_dict)
+            self._vectors = data.get("vectors", {})
+            self._stats.total_entries = len(self._entries)
+
+            if self.stats_file.is_file():
+                stats_raw = self.stats_file.read_text(encoding="utf-8")
+                self._stats = CacheStats.model_validate_json(stats_raw)
+
+            logger.info("cache.loaded", total_entries=len(self._entries))
+        except Exception as exc:
+            logger.warning("cache.load_failed", error=str(exc))

kernhell/cache/embedder.py

@@ -0,0 +1,104 @@
+"""Embedding generator and vector distance calculations for semantic caching.
+
+Supports:
+  1. `sentence-transformers` (`all-MiniLM-L6-v2`) for deep dense embeddings.
+  2. Built-in 384-dimensional projected subword frequency embedder for zero-dependency offline mode.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+from typing import Sequence
+
+import structlog
+
+logger = structlog.get_logger()
+
+EMBEDDING_DIM = 384
+
+
+def cosine_similarity(v1: Sequence[float], v2: Sequence[float]) -> float:
+    """Calculate the cosine similarity between two numeric vectors (range -1.0 to 1.0)."""
+    if len(v1) != len(v2) or not v1:
+        return 0.0
+
+    dot = sum(a * b for a, b in zip(v1, v2))
+    norm_a = math.sqrt(sum(a * a for a in v1))
+    norm_b = math.sqrt(sum(b * b for b in v2))
+
+    if norm_a == 0.0 or norm_b == 0.0:
+        return 0.0
+
+    return max(-1.0, min(1.0, dot / (norm_a * norm_b)))
+
+
+class SemanticEmbedder:
+    """Generates 384-dimensional dense vectors for semantic selector caching."""
+
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2") -> None:
+        self.model_name = model_name
+        self._st_model = None
+        self._tried_loading_st = False
+
+    def _get_sentence_transformer(self):
+        if not self._tried_loading_st:
+            self._tried_loading_st = True
+            try:
+                from sentence_transformers import SentenceTransformer
+                self._st_model = SentenceTransformer(self.model_name)
+                logger.info("embedder.sentence_transformers.loaded", model=self.model_name)
+            except Exception as exc:
+                logger.debug("embedder.sentence_transformers.unavailable", error=str(exc))
+                self._st_model = None
+        return self._st_model
+
+    def embed(self, text: str) -> list[float]:
+        """Compute 384-dimensional normalized vector for input text."""
+        model = self._get_sentence_transformer()
+        if model is not None:
+            try:
+                raw_vec = model.encode(text, normalize_embeddings=True)
+                return [float(x) for x in raw_vec]
+            except Exception as exc:
+                logger.warning("embedder.st_encode_failed.using_projected", error=str(exc))
+
+        return self._projected_dense_embed(text)
+
+    def _projected_dense_embed(self, text: str) -> list[float]:
+        """Deterministic subword feature hashing into a normalized 384D unit sphere.
+
+        Provides consistent semantic cosine similarity for identical and overlapping
+        selector intents without requiring external neural network weights.
+        """
+        vec = [0.0] * EMBEDDING_DIM
+        cleaned = text.lower().strip()
+        if not cleaned:
+            return vec
+
+        # Tokenize by alphanumeric words and punctuation
+        tokens = re.findall(r"\w+|[^\w\s]", cleaned)
+
+        # 1. Word token hashing
+        for token in tokens:
+            h = int(hashlib.md5(token.encode("utf-8")).hexdigest(), 16)
+            dim = h % EMBEDDING_DIM
+            sign = 1.0 if (h % 2 == 0) else -1.0
+            vec[dim] += sign * 1.5
+
+        # 2. Character n-gram hashing (captures partial renames like 'buy-now' vs 'purchase-btn')
+        for n in (3, 4):
+            for i in range(len(cleaned) - n + 1):
+                gram = cleaned[i : i + n]
+                h = int(hashlib.sha256(gram.encode("utf-8")).hexdigest(), 16)
+                dim = h % EMBEDDING_DIM
+                sign = 1.0 if (h % 2 == 0) else -1.0
+                vec[dim] += sign * 0.5
+
+        # Normalize vector to unit sphere (L2 norm)
+        norm = math.sqrt(sum(x * x for x in vec))
+        if norm > 0.0:
+            vec = [x / norm for x in vec]
+
+        return vec