cortex-loop 0.1.0a1__py3-none-any.whl

cortex/graveyard.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+from typing import Any, Iterable
+
+from .genome import GraveyardConfig
+from .store import SQLiteStore
+
+
+_WORD_RE = re.compile(r"[A-Za-z0-9_]+")
+_SYNONYM_CANONICAL = {
+    "redis": "cache",
+    "caching": "cache",
+    "latency": "timeout",
+    "slow": "timeout",
+    "slowness": "timeout",
+    "crash": "fail",
+    "crashed": "fail",
+    "failure": "fail",
+    "failed": "fail",
+    "error": "fail",
+    "errors": "fail",
+    "exception": "fail",
+    "exceptions": "fail",
+    "connection": "connect",
+    "connections": "connect",
+    "verification": "verify",
+    "verifications": "verify",
+    "verified": "verify",
+    "verifying": "verify",
+    "defense": "defend",
+    "defences": "defend",
+}
+
+
+@dataclass(slots=True)
+class GraveyardMatch:
+    entry_id: int
+    score: float
+    summary: str
+    reason: str
+    files: list[str]
+    keyword_overlap: list[str]
+    file_overlap: list[str]
+    semantic_score: float
+    created_at: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "entry_id": self.entry_id,
+            "score": round(self.score, 3),
+            "summary": self.summary,
+            "reason": self.reason,
+            "files": self.files,
+            "keyword_overlap": self.keyword_overlap,
+            "file_overlap": self.file_overlap,
+            "semantic_score": round(self.semantic_score, 3),
+            "created_at": self.created_at,
+        }
+
+
+class Graveyard:
+    def __init__(self, store: SQLiteStore, config: GraveyardConfig) -> None:
+        self.store = store
+        self.config = config
+
+    def record_failure(
+        self,
+        session_id: str | None,
+        summary: str,
+        reason: str,
+        files: Iterable[str] = (),
+    ) -> None:
+        if not self.config.enabled:
+            return
+        file_list = [str(path) for path in files]
+        keywords = sorted(self._keywords(summary) | self._keywords(reason))
+        self.store.insert_graveyard(
+            session_id=session_id,
+            summary=summary,
+            reason=reason,
+            files=file_list,
+            keywords=keywords,
+        )
+
+    def find_similar(
+        self,
+        summary: str,
+        files: Iterable[str] = (),
+        *,
+        max_matches: int | None = None,
+    ) -> list[GraveyardMatch]:
+        if not self.config.enabled:
+            return []
+
+        query_keywords = self._keywords(summary)
+        query_tokens = self._tokenize(summary)
+        query_token_set = set(query_tokens)
+        query_files = {self._norm_path(p) for p in files if p}
+        if not query_tokens and not query_files:
+            return []
+
+        corpus_entries = self.store.list_graveyard(limit=200)
+        entries = self._load_candidate_entries(query_tokens=query_tokens)
+        idf_source = corpus_entries or entries
+        df = Counter(token for entry in idf_source for token in {str(v) for v in entry.get("keywords", [])})
+        query_idf = {token: math.log((len(idf_source) + 1) / (df.get(token, 0) + 1)) + 1.0 for token in query_keywords}
+        query_weight = sum(query_idf.values()) or 1.0
+        scored: list[GraveyardMatch] = []
+        for entry in entries:
+            entry_keywords = {str(k) for k in entry.get("keywords", [])}
+            entry_tokens = self._tokenize(f"{entry.get('summary', '')} {entry.get('reason', '')}")
+            entry_files = {self._norm_path(p) for p in entry.get("files", [])}
+            keyword_overlap = sorted(query_keywords & entry_keywords)
+            file_overlap = sorted(query_files & entry_files)
+
+            keyword_score = sum(query_idf[token] for token in keyword_overlap) / query_weight
+            file_score = len(file_overlap) / max(1, len(query_files)) if query_files else 0.0
+            semantic_score = self._token_jaccard(query_token_set, set(entry_tokens))
+            if (
+                len(keyword_overlap) < self.config.min_keyword_overlap
+                and not file_overlap
+                and semantic_score < self.config.similarity_threshold
+            ):
+                continue
+
+            score = (keyword_score * 0.45) + (file_score * 0.25) + (semantic_score * 0.30)
+            if score < self.config.similarity_threshold:
+                continue
+            scored.append(
+                GraveyardMatch(
+                    entry_id=int(entry["id"]),
+                    score=score,
+                    summary=str(entry["summary"]),
+                    reason=str(entry["reason"]),
+                    files=list(entry["files"]),
+                    keyword_overlap=keyword_overlap,
+                    file_overlap=file_overlap,
+                    semantic_score=semantic_score,
+                    created_at=str(entry["created_at"]),
+                )
+            )
+
+        scored.sort(key=lambda m: (m.score, m.entry_id), reverse=True)
+        return scored[: (max_matches or self.config.max_matches)]
+
+    def _load_candidate_entries(self, *, query_tokens: list[str]) -> list[dict[str, object]]:
+        if not query_tokens:
+            return self.store.list_graveyard(limit=200)
+        candidates = self.store.list_graveyard_fts_candidates(tokens=query_tokens, limit=200, candidate_limit=80)
+        if not candidates:
+            return self.store.list_graveyard(limit=200)
+        return candidates
+
+    @staticmethod
+    def _keywords(text: str) -> set[str]:
+        return set(Graveyard._tokenize(text))
+
+    @staticmethod
+    def _tokenize(text: str) -> list[str]:
+        tokens: list[str] = []
+        for raw in _WORD_RE.findall(text):
+            token = Graveyard._normalize_token(raw)
+            if token:
+                tokens.append(token)
+        return tokens
+
+    @staticmethod
+    def _normalize_token(token: str) -> str:
+        value = token.lower().strip("_")
+        if len(value) <= 2:
+            return ""
+        if value.startswith("verif"):
+            value = "verify"
+        elif value.startswith("defenc") or value.startswith("defens"):
+            value = "defend"
+        if value.endswith("ies") and len(value) > 4:
+            value = value[:-3] + "y"
+        elif value.endswith("ing") and len(value) > 5:
+            value = value[:-3]
+        elif value.endswith("ed") and len(value) > 4:
+            value = value[:-2]
+        elif value.endswith("s") and len(value) > 3:
+            value = value[:-1]
+        return _SYNONYM_CANONICAL.get(value, value)
+
+    @staticmethod
+    def _token_jaccard(left: set[str], right: set[str]) -> float:
+        if not left or not right:
+            return 0.0
+        union = left | right
+        if not union:
+            return 0.0
+        return len(left & right) / len(union)
+
+    @staticmethod
+    def _norm_path(path: str) -> str:
+        parts = [p for p in str(PurePosixPath(path)).split("/") if p not in {"", "."}]
+        return "/".join(parts)
+
+
+def explainability_warnings(matches: list[dict[str, Any]]) -> list[str]:
+    if not matches:
+        return []
+    top = matches[0]
+    summary = str(top.get("summary") or "").strip()
+    score = top.get("score")
+    semantic_score = top.get("semantic_score")
+    keyword_overlap = [str(v).strip() for v in top.get("keyword_overlap", []) if str(v).strip()]
+    file_overlap = [str(v).strip() for v in top.get("file_overlap", []) if str(v).strip()]
+    parts = ["Top graveyard match"]
+    if summary:
+        parts.append(f"summary='{summary[:120]}'")
+    if isinstance(score, (int, float)):
+        parts.append(f"score={float(score):.3f}")
+    if isinstance(semantic_score, (int, float)):
+        parts.append(f"semantic={float(semantic_score):.3f}")
+    if keyword_overlap:
+        parts.append("keyword_overlap=" + ",".join(keyword_overlap[:5]))
+    if file_overlap:
+        parts.append("file_overlap=" + ",".join(file_overlap[:3]))
+    return ["; ".join(parts)]

cortex/hooks/__init__.py

@@ -0,0 +1,27 @@
+"""Runtime hook entrypoints for Cortex."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cortex.core import CortexKernel
+
+
+def marker(
+    label: str,
+    *,
+    session_id: str,
+    root: str | Path = ".",
+    config_path: str | Path | None = None,
+) -> dict[str, object]:
+    token = str(label).strip()
+    if not token:
+        raise ValueError("marker() requires a non-empty label.")
+    session_token = str(session_id or "").strip()
+    if not session_token:
+        raise ValueError("marker() requires session_id. Use marker(label, session_id='sess-...').")
+    payload: dict[str, object] = {"label": token, "session_id": session_token}
+    return CortexKernel(root=root, config_path=config_path).dispatch("session_marker", payload)
+
+
+__all__ = ["marker"]

cortex/hooks/_shared.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from cortex.core import CortexKernel
+
+HOOK_SCHEMA_NATIVE = "native_hook_v1"
+HOOK_SCHEMA_LEGACY = "legacy_json_v0"
+_NATIVE_ALIAS = "".join(["cl", "aude_native_v1"])
+_STOP_PRIORITY_PREFIXES = (
+    "Structured stop payload is required",
+    "Strict mode rejects Stop message-fallback payloads",
+    "Truth claims reported gaps:",
+    "Requirement audit reported gaps:",
+    "Missing challenge coverage for categories:",
+    "Challenge coverage '",
+    "Stop attempt is highly similar to the previous failed Stop;",
+)
+_STOP_IGNORED_PREFIXES = ("Using ", "Truth claims note:", "Requirement audit note:")
+
+
+def run_hook(
+    *,
+    hook_name: str,
+    event_name: str,
+    argv: list[str] | None = None,
+) -> int:
+    args = _parse_args(argv)
+    try:
+        if args.adapter is not None:
+            raise ValueError(
+                "--adapter is no longer supported. Configure [runtime].adapter in cortex.toml."
+            )
+        payload = _read_stdin_json()
+        kernel = CortexKernel(root=args.root, config_path=args.config)
+        result = kernel.dispatch(event_name, payload)
+        print(json.dumps(_format_hook_output(hook_name=hook_name, result=result, schema_version=args.schema_version)))
+        return 0
+    except Exception as exc:  # noqa: BLE001
+        print(json.dumps(_format_hook_error(hook_name=hook_name, error=str(exc), schema_version=args.schema_version)))
+        return 1
+
+
+def _read_stdin_json() -> dict[str, object]:
+    raw = sys.stdin.read().strip()
+    if not raw:
+        return {}
+    data = json.loads(raw)
+    if not isinstance(data, dict):
+        raise ValueError("Hook payload must be a JSON object")
+    return data
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--root", default=".")
+    parser.add_argument("--config")
+    parser.add_argument("--adapter")
+    parser.add_argument("--schema-version", default=HOOK_SCHEMA_LEGACY)
+    args = parser.parse_args([] if argv is None else argv)
+    args.schema_version = _normalize_schema_version(str(args.schema_version))
+    return args
+
+
+def _normalize_schema_version(raw: str) -> str:
+    schema_version = str(raw or "").strip()
+    if schema_version in {HOOK_SCHEMA_NATIVE, _NATIVE_ALIAS}:
+        return HOOK_SCHEMA_NATIVE
+    if schema_version == HOOK_SCHEMA_LEGACY:
+        return HOOK_SCHEMA_LEGACY
+    raise ValueError(
+        "Unsupported --schema-version. Use one of: "
+        f"{HOOK_SCHEMA_NATIVE}, {_NATIVE_ALIAS}, {HOOK_SCHEMA_LEGACY}"
+    )
+
+
+def _format_hook_output(*, hook_name: str, result: dict[str, Any], schema_version: str) -> dict[str, Any]:
+    if schema_version == HOOK_SCHEMA_LEGACY:
+        return result
+    if hook_name == "PreToolUse":
+        proceed = bool(result.get("proceed", True))
+        decision = "allow" if proceed else "deny"
+        output: dict[str, Any] = {
+            "permissionDecision": decision,
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": decision,
+            },
+        }
+        if not proceed:
+            output["hookSpecificOutput"]["permissionDecisionReason"] = _primary_reason(hook_name, result)
+        return output
+    if hook_name in {"PostToolUse", "Stop"}:
+        if hook_name == "Stop" and _is_stuck_result(result):
+            return {"continue": False, "stopReason": _primary_reason(hook_name, result)}
+        if bool(result.get("proceed", True)):
+            return {}
+        return {"decision": "block", "reason": _primary_reason(hook_name, result)}
+    return result
+
+
+def _format_hook_error(*, hook_name: str, error: str, schema_version: str) -> dict[str, Any]:
+    if schema_version == HOOK_SCHEMA_LEGACY:
+        return {"ok": False, "hook": hook_name, "error": error}
+    if hook_name == "PreToolUse":
+        return {
+            "permissionDecision": "deny",
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": error,
+            }
+        }
+    if hook_name in {"PostToolUse", "Stop"}:
+        return {"decision": "block", "reason": error}
+    return {"decision": "block", "reason": error}
+
+
+def _primary_reason(hook_name: str, result: dict[str, Any]) -> str:
+    if _is_stuck_result(result):
+        return _stuck_reason(result)
+    if hook_name == "Stop":
+        stop_reason = _stop_reason(result)
+        if stop_reason:
+            return stop_reason
+    warning = next((item for item in _warning_strings(result) if item), "")
+    if warning:
+        return warning
+    if hook_name == "Stop":
+        return "Cortex stop path blocked completion."
+    if hook_name == "PostToolUse":
+        return "Cortex post-tool gate blocked continuation."
+    return "Cortex denied tool execution."
+
+
+def _stop_reason(result: dict[str, Any]) -> str | None:
+    warnings = _warning_strings(result)
+    warning = next((item for item in warnings if item.startswith(_STOP_PRIORITY_PREFIXES)), None)
+    if warning:
+        return warning
+    return next((item for item in warnings if not item.startswith(_STOP_IGNORED_PREFIXES)), None)
+
+
+def _is_stuck_result(result: dict[str, Any]) -> bool:
+    return bool(result.get("stuck_declared")) or str(result.get("feedback_mode") or "") == "stuck"
+
+
+def _warning_strings(result: dict[str, Any]) -> list[str]:
+    warnings = result.get("warnings")
+    if not isinstance(warnings, list):
+        return []
+    return [str(raw_warning or "").strip() for raw_warning in warnings if str(raw_warning or "").strip()]
+
+
+def _stuck_reason(result: dict[str, Any]) -> str:
+    stuck = result.get("stuck_declaration")
+    if isinstance(stuck, dict):
+        check = str(stuck.get("check") or "").strip()
+        obstacle = str(stuck.get("obstacle") or "").strip()
+        if check and obstacle:
+            return f"Cortex reported stuck on {check}: {obstacle}"
+        if obstacle:
+            return f"Cortex reported stuck: {obstacle}"
+    return "Cortex reported stuck and could not complete the requested evidence boundary."

cortex/hooks/post_tool_use.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import sys
+
+from ._shared import run_hook
+
+
+def main(argv: list[str] | None = None) -> int:
+    return run_hook(hook_name="PostToolUse", event_name="post_tool_use", argv=argv)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

cortex/hooks/pre_tool_use.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import sys
+
+from ._shared import run_hook
+
+
+def main(argv: list[str] | None = None) -> int:
+    return run_hook(hook_name="PreToolUse", event_name="pre_tool_use", argv=argv)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

cortex/hooks/session_start.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import sys
+
+from ._shared import run_hook
+
+
+def main(argv: list[str] | None = None) -> int:
+    return run_hook(hook_name="SessionStart", event_name="session_start", argv=argv)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

cortex/hooks/stop.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import sys
+
+from ._shared import run_hook
+
+
+def main(argv: list[str] | None = None) -> int:
+    return run_hook(hook_name="Stop", event_name="stop", argv=argv)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))