errlore 0.1.0__py3-none-any.whl

errlore/__init__.py

@@ -0,0 +1,16 @@
+"""errlore -- memory for AI agents that learns from failures."""
+
+__version__ = "0.1.0"
+
+from errlore.facade import AgentMemory, Injection
+from errlore.lessons.store import LessonStore
+from errlore.trust import FeedbackSignal, TrustEngine
+
+__all__ = [
+    "AgentMemory",
+    "FeedbackSignal",
+    "Injection",
+    "LessonStore",
+    "TrustEngine",
+    "__version__",
+]

errlore/errmem/__init__.py

@@ -0,0 +1,21 @@
+"""Error memory (Amygdala) — model weakness tracking, pattern detection, prompt injection.
+
+Public API:
+    classify_error    — regex extraction of ErrorType from exception/stacktrace/message
+    ErrorTracker      — record_error / get_model_profile, persisted via errlore.io
+    PatternDetector   — group (model, error_type, task_type), similarity with RU/EN stemming
+    WarningInjector   — build_warning / get_penalty for prompt injection
+    sanitize_description — strip raw JSON / overlong text from descriptions
+"""
+
+from errlore.errmem.classifier import classify_error
+from errlore.errmem.injector import WarningInjector
+from errlore.errmem.patterns import PatternDetector
+from errlore.errmem.tracker import ErrorTracker
+
+__all__ = [
+    "ErrorTracker",
+    "PatternDetector",
+    "WarningInjector",
+    "classify_error",
+]

errlore/errmem/classifier.py

@@ -0,0 +1,54 @@
+"""Auto-classification of error types from string messages and stacktraces.
+
+Solves the generic "Error" problem (61 % of records in NEXUS audit) by
+extracting a concrete type (ImportError, TimeoutError, etc.) from text.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Captures: ValueError, TimeoutError, ConnectionException, RuntimeWarning, etc.
+_ERROR_TYPE_RE = re.compile(
+    r"\b([A-Z]\w*(?:Error|Exception|Warning|Timeout|Fault|Failure))\b",
+)
+
+
+def classify_error(
+    error: Exception | None = None,
+    message: str = "",
+    stacktrace: str = "",
+) -> str:
+    """Extract the most specific error type from available information.
+
+    Priority:
+        1. Exception class name (if an object is provided).
+        2. Last match in the stacktrace (most specific).
+        3. First match in the message text.
+        4. Fallback: ``"UnclassifiedError"``.
+
+    Args:
+        error: Exception object, if available.
+        message: Textual error description.
+        stacktrace: Full stacktrace string.
+
+    Returns:
+        Concrete error type name, e.g. ``"ImportError"``.
+    """
+    # 1. Direct extraction from exception object
+    if error is not None:
+        return type(error).__name__
+
+    # 2. Stacktrace — search from the end (last error is the most specific)
+    if stacktrace:
+        matches = _ERROR_TYPE_RE.findall(stacktrace)
+        if matches:
+            return str(matches[-1])
+
+    # 3. Message — first occurrence
+    if message:
+        match = _ERROR_TYPE_RE.search(message)
+        if match:
+            return match.group(1)
+
+    return "UnclassifiedError"

errlore/errmem/injector.py

@@ -0,0 +1,156 @@
+"""Warning injector — builds prompt warnings from error memory.
+
+Formats known model weaknesses and past errors into a structured
+block suitable for system-prompt injection.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+
+from errlore.errmem.patterns import PatternDetector
+from errlore.errmem.tracker import ErrorTracker
+from errlore.sanitize import extract_readable_from_json
+
+logger = logging.getLogger("errlore.errmem")
+
+_MAX_DESCRIPTION_LEN = 200
+_RAW_JSON_RE = re.compile(r"^\s*[\{`]")
+
+
+def sanitize_description(text: str) -> str | None:
+    """Sanitize a description for human-readable prompt injection.
+
+    Rules:
+        - Strip to ``_MAX_DESCRIPTION_LEN`` characters.
+        - Collapse runs of whitespace into a single space.
+        - If the text looks like raw JSON (starts with ``{`` or backticks),
+          try to extract a readable ``"message"`` / ``"error"`` field;
+          otherwise discard the entry entirely (return ``None``).
+
+    Args:
+        text: Raw description string.
+
+    Returns:
+        Cleaned string, or ``None`` if the input is unsalvageable junk.
+    """
+    text = text.strip()
+    if not text:
+        return None
+
+    if _RAW_JSON_RE.match(text):
+        extracted = extract_readable_from_json(text)
+        if extracted is None:
+            return None
+        text = extracted
+
+    # B8: collapse whitespace (consistent with sanitize.py).
+    text = re.sub(r"\s+", " ", text).strip()
+
+    if len(text) > _MAX_DESCRIPTION_LEN:
+        text = text[: _MAX_DESCRIPTION_LEN - 3] + "..."
+
+    return text
+
+
+class WarningInjector:
+    """Build prompt-injection warnings from error memory.
+
+    Combines model weaknesses (frequent error types) and past errors
+    on similar task types into a ``KNOWN ISSUES`` block.
+
+    auto_tuner_warnings from NEXUS are intentionally **not** ported
+    (dead bridge, NEXUS-specific coupling).
+
+    Args:
+        tracker: :class:`ErrorTracker` instance.
+        detector: :class:`PatternDetector` instance.
+        top_n: Maximum number of weakness lines to include.
+            Defaults to ``3``.
+    """
+
+    def __init__(
+        self,
+        tracker: ErrorTracker,
+        detector: PatternDetector,
+        *,
+        top_n: int = 3,
+    ) -> None:
+        self._tracker = tracker
+        self._detector = detector
+        self._top_n = top_n
+
+    def build_warning(self, model: str, task_type: str) -> str:
+        """Build a warning string for prompt injection.
+
+        Output format (verbatim)::
+
+            KNOWN ISSUES:
+            - {error_type} (x{count})
+            - Past error on similar task: {description}
+
+        Args:
+            model: Model name.
+            task_type: Task category.
+
+        Returns:
+            Warning string, or ``""`` if there is nothing to report.
+        """
+        # C2: single read of model_accuracy.jsonl instead of two separate
+        # calls (get_model_weaknesses + get_errors_for_task_type each did
+        # a full file read).  The tracker's _read_all is now cached via
+        # JSONLWriter.read_all mtime+size cache, so the second call hits
+        # the cache automatically.  No API change needed -- the cache in
+        # JSONLWriter handles this transparently.
+        weaknesses = self._tracker.get_model_weaknesses(model)
+        past_errors = self._tracker.get_errors_for_task_type(task_type)
+
+        if not weaknesses and not past_errors:
+            return ""
+
+        parts: list[str] = ["KNOWN ISSUES:"]
+
+        for w in weaknesses[: self._top_n]:
+            parts.append(f"- {w}")
+
+        for e in past_errors[:2]:
+            raw_desc = str(e.get("description", ""))
+            desc = sanitize_description(raw_desc)
+            if desc is None:
+                continue
+            parts.append(f"- Past error on similar task: {desc}")
+
+        # If we only have the header line (all past_errors were junk), skip
+        if len(parts) <= 1:
+            return ""
+
+        return "\n".join(parts)
+
+    def get_penalty(self, model: str, task_type: str) -> float:
+        """Calculate an error-history penalty for model routing.
+
+        Combines weakness count and past-error similarity into a
+        single ``[0.0, 1.0]`` score.  Higher means more errors
+        on record for this ``(model, task_type)`` pair.
+
+        Args:
+            model: Model name.
+            task_type: Task category used as a similarity probe.
+
+        Returns:
+            Penalty score in ``[0.0, 1.0]``.
+        """
+        errors = self._tracker.get_model_errors(model)
+        if not errors:
+            return 0.0
+
+        # Component 1: weakness-based penalty (capped at 0.5)
+        weaknesses = self._tracker.get_model_weaknesses(model)
+        weakness_penalty = min(0.5, len(weaknesses) * 0.1)
+
+        # Component 2: similarity-based penalty (capped at 0.5)
+        similarity = self._detector.similarity_score(task_type, errors)
+        similarity_penalty = min(0.5, similarity * 0.5)
+
+        return min(1.0, weakness_penalty + similarity_penalty)

errlore/errmem/patterns.py

@@ -0,0 +1,193 @@
+"""Error pattern detection with RU/EN stemming-based similarity.
+
+Groups errors by ``(model, error_type, task_type)`` and surfaces patterns
+whose frequency meets a configurable threshold.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from typing import Any
+
+_CYRILLIC_RE = re.compile(r"^[а-яёА-ЯЁ]+$")
+
+_STOP_WORDS_RU = frozenset(
+    {
+        "и",
+        "в",
+        "на",
+        "с",
+        "по",
+        "для",
+        "из",
+        "к",
+        "от",
+        "до",
+        "не",
+        "но",
+        "а",
+        "что",
+        "как",
+        "это",
+        "при",
+        "за",
+        "или",
+        "же",
+        "ли",
+        "бы",
+        "то",
+        "его",
+        "её",
+        "их",
+        "он",
+        "она",
+        "мы",
+        "вы",
+        "они",
+        "был",
+        "быть",
+        "будет",
+        "если",
+        "так",
+        "уже",
+        "ещё",
+        "тоже",
+        "также",
+        "только",
+        "нет",
+        "да",
+    },
+)
+
+_STOP_WORDS_EN = frozenset(
+    {
+        "the",
+        "a",
+        "an",
+        "is",
+        "are",
+        "was",
+        "were",
+        "be",
+        "been",
+        "to",
+        "of",
+        "in",
+        "for",
+        "on",
+        "with",
+        "at",
+        "by",
+        "from",
+        "and",
+        "or",
+        "not",
+        "but",
+        "if",
+        "it",
+        "this",
+        "that",
+    },
+)
+
+
+def _stem_ru(word: str) -> str:
+    """Naive suffix stemmer for Russian words."""
+    if len(word) <= 4 or not _CYRILLIC_RE.match(word):
+        return word
+    for suffix_len in (3, 2):
+        if len(word) > suffix_len + 2:
+            return word[:-suffix_len]
+    return word
+
+
+def _normalize_words(text: str) -> set[str]:
+    """Lowercase, stem, and remove stop-words for RU/EN text."""
+    words = set(text.lower().split())
+    words -= _STOP_WORDS_RU
+    words -= _STOP_WORDS_EN
+    return {_stem_ru(w) for w in words if len(w) > 1}
+
+
+class PatternDetector:
+    """Detect recurring error patterns from a list of error entries.
+
+    Groups by ``(model, error_type, task_type)`` and returns groups
+    whose frequency is ``>= min_occurrences``.
+
+    Args:
+        min_occurrences: Minimum repeat count to be considered a pattern.
+            Defaults to ``3``.
+    """
+
+    def __init__(self, min_occurrences: int = 3) -> None:
+        self._min_occurrences = min_occurrences
+
+    def detect(self, errors: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Detect recurring error patterns.
+
+        Args:
+            errors: List of error entry dicts.
+
+        Returns:
+            List of pattern dicts with ``model``, ``error_type``,
+            ``task_type``, and ``occurrences`` keys.
+        """
+        counter: Counter[tuple[str, str, str]] = Counter()
+        for e in errors:
+            key = (
+                str(e.get("model", "unknown")),
+                str(e.get("error_type", "unknown")),
+                str(e.get("task_type", "unknown")),
+            )
+            counter[key] += 1
+
+        patterns: list[dict[str, Any]] = []
+        for (model, error_type, task_type), count in counter.most_common():
+            if count >= self._min_occurrences:
+                patterns.append(
+                    {
+                        "model": model,
+                        "error_type": error_type,
+                        "task_type": task_type,
+                        "occurrences": count,
+                    },
+                )
+
+        return patterns
+
+    def similarity_score(
+        self,
+        task_description: str,
+        past_errors: list[dict[str, Any]],
+    ) -> float:
+        """Estimate similarity of a new task to past errors.
+
+        Uses word-overlap heuristic with RU/EN stemming and stop-word removal.
+
+        Args:
+            task_description: Description of the current task.
+            past_errors: List of past error entries.
+
+        Returns:
+            Similarity score in ``[0.0, 1.0]``.
+        """
+        if not past_errors or not task_description:
+            return 0.0
+
+        task_words = _normalize_words(task_description)
+        if not task_words:
+            return 0.0
+
+        max_overlap = 0.0
+        for error in past_errors:
+            description = str(error.get("description", ""))
+            task_type = str(error.get("task_type", ""))
+            error_words = _normalize_words(f"{description} {task_type}")
+            if not error_words:
+                continue
+            overlap = len(task_words & error_words) / len(task_words)
+            max_overlap = max(max_overlap, overlap)
+
+        return min(1.0, max_overlap)

errlore/errmem/tracker.py

@@ -0,0 +1,157 @@
+"""Model error tracker (Amygdala) — records errors and builds weakness profiles.
+
+Persists data to ``model_accuracy.jsonl`` via :class:`errlore.io.JSONLWriter`.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections import Counter
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from errlore.io import JSONLWriter
+
+logger = logging.getLogger("errlore.errmem")
+
+
+class ErrorTracker:
+    """Track per-model errors and build weakness profiles.
+
+    All data is stored in a single append-only JSONL file
+    (``data_dir / "model_accuracy.jsonl"``).
+
+    Args:
+        data_dir: Directory for persistent storage.
+        min_occurrences: Minimum repeat count to consider something a weakness.
+            Defaults to ``3``.
+        writer: Optional :class:`JSONLWriter` instance (shared across modules).
+    """
+
+    def __init__(
+        self,
+        data_dir: Path,
+        *,
+        min_occurrences: int = 3,
+        writer: JSONLWriter | None = None,
+    ) -> None:
+        self._data_dir = Path(data_dir)
+        self._data_dir.mkdir(parents=True, exist_ok=True)
+        self._accuracy_file = self._data_dir / "model_accuracy.jsonl"
+        self._lock = threading.Lock()
+        self._min_occurrences = min_occurrences
+        self._writer = writer or JSONLWriter()
+
+    # -- write ----------------------------------------------------------
+
+    def record_error(
+        self,
+        model: str,
+        task_type: str,
+        error: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Record a model error.
+
+        Args:
+            model: Model name.
+            task_type: Task category.
+            error: Dict with ``type``, ``description``, ``severity`` keys.
+
+        Returns:
+            The persisted entry dict.
+        """
+        entry: dict[str, Any] = {
+            "timestamp": datetime.now(UTC).isoformat(),
+            "model": model,
+            "task_type": task_type,
+            "error_type": error.get("type", "unknown"),
+            "description": error.get("description", ""),
+            "severity": error.get("severity", "medium"),
+        }
+        self._writer.append(self._accuracy_file, entry)
+        return entry
+
+    # -- read -----------------------------------------------------------
+
+    def get_model_errors(self, model: str) -> list[dict[str, Any]]:
+        """Return all recorded errors for a specific model."""
+        all_entries = self._read_all()
+        return [e for e in all_entries if e.get("model") == model]
+
+    def get_errors_for_task_type(self, task_type: str) -> list[dict[str, Any]]:
+        """Return errors for a specific task type."""
+        all_entries = self._read_all()
+        return [e for e in all_entries if e.get("task_type") == task_type]
+
+    def get_model_weaknesses(
+        self,
+        model: str,
+        min_occurrences: int | None = None,
+    ) -> list[str]:
+        """Return known weaknesses for a model based on error patterns.
+
+        Args:
+            model: Model name.
+            min_occurrences: Override the instance default threshold.
+
+        Returns:
+            List of weakness descriptions like ``"TimeoutError (x5)"``.
+        """
+        if min_occurrences is None:
+            min_occurrences = self._min_occurrences
+
+        errors = self.get_model_errors(model)
+        if not errors:
+            return []
+
+        counter: Counter[str] = Counter()
+        for e in errors:
+            error_type = e.get("error_type", "unknown")
+            counter[error_type] += 1
+
+        weaknesses: list[str] = []
+        for error_type, count in counter.most_common():
+            if count >= min_occurrences:
+                weaknesses.append(f"{error_type} (x{count})")
+
+        return weaknesses
+
+    def get_model_profile(self, model: str) -> dict[str, Any]:
+        """Return an aggregate error profile for a model.
+
+        Returns:
+            Dict with ``errors`` (total count), ``last_error`` (ISO timestamp),
+            and ``weaknesses`` (list of weakness strings).
+        """
+        errors = self.get_model_errors(model)
+        profile: dict[str, Any] = {
+            "errors": len(errors),
+            "last_error": errors[-1].get("timestamp", "") if errors else "",
+            "weaknesses": self.get_model_weaknesses(model),
+        }
+        return profile
+
+    def get_model_stats(self) -> dict[str, dict[str, Any]]:
+        """Return per-model error statistics.
+
+        Returns:
+            ``{model_name: {"errors": N, "last_error": "timestamp"}}``.
+        """
+        stats: dict[str, dict[str, Any]] = {}
+        all_entries = self._read_all()
+        for entry in all_entries:
+            model = str(entry.get("model", "unknown"))
+            if model not in stats:
+                stats[model] = {"errors": 0, "last_error": ""}
+            stats[model]["errors"] += 1
+            stats[model]["last_error"] = str(entry.get("timestamp", ""))
+        return stats
+
+    # -- internals ------------------------------------------------------
+
+    def _read_all(self) -> list[dict[str, Any]]:
+        """Read all entries from the accuracy file (thread-safe)."""
+        with self._lock:
+            return self._writer.read_all(self._accuracy_file)