jevguard-core 1.0.0__py3-none-any.whl

jevguard/__init__.py

@@ -0,0 +1,63 @@
+"""
+JevGuard - High-Performance Deterministic Runtime for TypeSafe AI / Jev.
+Provides closed-world optimization, certainty calibration, state pruning,
+zero-token deterministic caching, and episodic session memory.
+"""
+
+from .models import (
+    Question,
+    Noul,
+    Score,
+    Choice,
+    NoulAnswer,
+    ScoreAnswer,
+    ChoiceAnswer,
+    EvaluationResponse,
+    EvaluationResult
+)
+from .client import JevGuardClient
+from .optimizer import StatePruner, QuestionOptimizer, ESCAPE_OPTION_KEY
+from .calibrator import ResponseCalibrator, CertaintyCalibrator
+from .cache import DeterministicCache, SemanticCache
+from .memory import EpisodicMemory
+from .exceptions import (
+    JevGuardError,
+    JevGuardConfigError,
+    JevGuardNetworkError,
+    JevGuardTimeoutError,
+    JevGuardHTTPError,
+    JevGuardAuthenticationError,
+    JevGuardRateLimitError,
+    JevGuardServerError
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "JevGuardClient",
+    "Question",
+    "Noul",
+    "Score",
+    "Choice",
+    "NoulAnswer",
+    "ScoreAnswer",
+    "ChoiceAnswer",
+    "EvaluationResponse",
+    "EvaluationResult",
+    "StatePruner",
+    "QuestionOptimizer",
+    "ResponseCalibrator",
+    "CertaintyCalibrator",
+    "DeterministicCache",
+    "SemanticCache",
+    "EpisodicMemory",
+    "ESCAPE_OPTION_KEY",
+    "JevGuardError",
+    "JevGuardConfigError",
+    "JevGuardNetworkError",
+    "JevGuardTimeoutError",
+    "JevGuardHTTPError",
+    "JevGuardAuthenticationError",
+    "JevGuardRateLimitError",
+    "JevGuardServerError"
+]

jevguard/cache.py

@@ -0,0 +1,331 @@
+"""
+jevguard.cache - Zero-Token Deterministic Hashing Cache for TypeSafe AI / Jev.
+Stores decisions indexed by SHA-256 fingerprints of canonical JSON with volatile key masking.
+"""
+
+import contextlib
+import hashlib
+import json
+import logging
+import sqlite3
+import threading
+import time
+from typing import Any, Dict, Generator, Iterable, Optional, Set
+
+import os
+
+logger = logging.getLogger("jevguard.cache")
+
+DEFAULT_VOLATILE_KEYS: Set[str] = {
+    "timestamp",
+    "trace_id",
+    "span_id",
+    "request_id",
+    "correlation_id",
+    "nonce",
+    "traceid",
+    "requestid",
+    "x_trace_id",
+    "x_request_id",
+    "x_correlation_id",
+    "xtraceid",
+    "xrequestid"
+}
+
+
+class DeterministicCache:
+    """Provides instant 0-token response retrieval for repeated queries."""
+
+    def __init__(
+        self,
+        db_path: str = "jevguard_cache.db",
+        max_memory_items: int = 500,
+        default_ignore_keys: Optional[Iterable[str]] = None,
+        ttl_seconds: Optional[float] = None
+    ):
+        self.db_path = db_path
+        self.max_memory_items = max_memory_items
+        raw_ttl = os.environ.get("JEVGUARD_CACHE_TTL")
+        if raw_ttl is not None:
+            try:
+                self.ttl_seconds = float(raw_ttl)
+            except (ValueError, TypeError):
+                self.ttl_seconds = 3600.0
+        elif ttl_seconds is not None:
+            self.ttl_seconds = float(ttl_seconds)
+        else:
+            self.ttl_seconds = 3600.0
+        self.default_ignore_keys = (
+            set(DEFAULT_VOLATILE_KEYS).union({str(k).strip().lower().replace("-", "_") for k in default_ignore_keys})
+            if default_ignore_keys is not None
+            else set(DEFAULT_VOLATILE_KEYS)
+        )
+        self._memory_lru: Dict[str, Dict[str, Any]] = {}
+        self._lock = threading.RLock()
+        self._local = threading.local()
+        self._shared_conn: Optional[sqlite3.Connection] = None
+
+        if self.db_path == ":memory:":
+            self._shared_conn = sqlite3.connect(":memory:", check_same_thread=False, timeout=60.0)
+            self._shared_conn.row_factory = sqlite3.Row
+            try:
+                self._shared_conn.execute("PRAGMA busy_timeout = 60000")
+            except Exception:
+                pass
+
+        self.stats = {
+            "hits": 0,
+            "misses": 0,
+            "tokens_saved": 0
+        }
+        self._init_db()
+
+    @contextlib.contextmanager
+    def _get_connection(self) -> Generator[sqlite3.Connection, None, None]:
+        if self._shared_conn is not None:
+            with self._lock:
+                yield self._shared_conn
+        else:
+            conn = getattr(self._local, "conn", None)
+            if conn is None:
+                conn = sqlite3.connect(self.db_path, timeout=60.0)
+                conn.row_factory = sqlite3.Row
+                try:
+                    conn.execute("PRAGMA busy_timeout = 60000")
+                    conn.execute("PRAGMA journal_mode=WAL")
+                    conn.execute("PRAGMA synchronous=NORMAL")
+                except Exception as e:
+                    logger.debug("PRAGMA setup notice: %s", e)
+                self._local.conn = conn
+            with self._lock:
+                yield conn
+
+    def _init_db(self) -> None:
+        with self._get_connection() as conn:
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS evaluation_cache (
+                    fingerprint TEXT PRIMARY KEY,
+                    model TEXT NOT NULL,
+                    response_json TEXT NOT NULL,
+                    created_at REAL NOT NULL,
+                    hit_count INTEGER DEFAULT 0,
+                    tokens_estimate INTEGER DEFAULT 0
+                )
+            """)
+            conn.commit()
+
+    @classmethod
+    def _strip_volatile_keys(cls, data: Any, ignore_keys: Set[str], seen: Optional[Set[int]] = None) -> Any:
+        if seen is None:
+            seen = set()
+
+        if isinstance(data, (dict, list, tuple, set, frozenset)):
+            obj_id = id(data)
+            if obj_id in seen:
+                return "<cyclic_ref>"
+            seen.add(obj_id)
+        else:
+            obj_id = None
+
+        try:
+            if isinstance(data, dict):
+                cleaned = {}
+                for k, v in data.items():
+                    norm_k = str(k).strip().lower().replace("-", "_")
+                    if norm_k in ignore_keys:
+                        continue
+                    cleaned[str(k)] = cls._strip_volatile_keys(v, ignore_keys, seen=seen)
+                return cleaned
+            elif isinstance(data, list):
+                return [cls._strip_volatile_keys(item, ignore_keys, seen=seen) for item in data]
+            elif isinstance(data, tuple):
+                return tuple(cls._strip_volatile_keys(item, ignore_keys, seen=seen) for item in data)
+            elif isinstance(data, (set, frozenset)):
+                items = [cls._strip_volatile_keys(item, ignore_keys, seen=seen) for item in data]
+                try:
+                    return sorted(items)
+                except TypeError:
+                    return sorted(items, key=lambda x: str(x))
+            return data
+        finally:
+            if obj_id is not None:
+                seen.remove(obj_id)
+
+    @classmethod
+    def compute_fingerprint(
+        cls,
+        model: str = "jev-latest",
+        state: Any = None,
+        wire_questions: Optional[Dict[str, Any]] = None,
+        ignore_keys: Optional[Iterable[str]] = None
+    ) -> str:
+        # Detect positional invocation without model: compute_fingerprint(state, questions, ignore_keys)
+        if isinstance(model, (dict, list)):
+            if wire_questions is not None and not isinstance(wire_questions, dict):
+                ignore_keys = wire_questions
+            wire_questions = state if isinstance(state, dict) else {}
+            state = model
+            model = "jev-latest"
+
+        target_model = model or "jev-latest"
+        target_state = state if state is not None else {}
+        target_questions = wire_questions if wire_questions is not None else {}
+
+        keys_to_ignore = (
+            set(DEFAULT_VOLATILE_KEYS).union({str(k).strip().lower().replace("-", "_") for k in ignore_keys})
+            if ignore_keys is not None
+            else set(DEFAULT_VOLATILE_KEYS)
+        )
+        filtered_state = cls._strip_volatile_keys(target_state, keys_to_ignore) if keys_to_ignore else target_state
+
+        canonical_struct = {
+            "model": target_model.strip().lower(),
+            "state": filtered_state,
+            "questions": target_questions
+        }
+        canonical_bytes = json.dumps(
+            canonical_struct,
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=True
+        ).encode("utf-8")
+        return hashlib.sha256(canonical_bytes).hexdigest()
+
+    def set(
+        self,
+        fingerprint: str,
+        data: Dict[str, Any],
+        model: str = "jev-latest",
+        input_tokens_estimate: int = 0
+    ) -> None:
+        """Alias for put() following standard key-value cache conventions."""
+        self.put(fingerprint, model, data, input_tokens_estimate)
+
+    def get(self, fingerprint: str) -> Optional[Dict[str, Any]]:
+        with self._lock:
+            if fingerprint in self._memory_lru:
+                item = self._memory_lru[fingerprint]
+                entry_time = item.get("created_at", 0.0)
+                if self.ttl_seconds > 0 and (time.time() - entry_time) > self.ttl_seconds:
+                    del self._memory_lru[fingerprint]
+                else:
+                    self.stats["hits"] += 1
+                    tokens = item.get("tokens_estimate", 0)
+                    self.stats["tokens_saved"] += tokens
+                    self._promote_lru(fingerprint, item["data"], tokens, created_at=entry_time)
+                    return item["data"]
+
+        try:
+            with self._get_connection() as conn:
+                cur = conn.execute(
+                    "SELECT response_json, tokens_estimate, created_at FROM evaluation_cache WHERE fingerprint = ?",
+                    (fingerprint,)
+                )
+                row = cur.fetchone()
+                if row:
+                    entry_created_at = row["created_at"]
+                    if self.ttl_seconds > 0 and (time.time() - entry_created_at) > self.ttl_seconds:
+                        conn.execute("DELETE FROM evaluation_cache WHERE fingerprint = ?", (fingerprint,))
+                        conn.commit()
+                    else:
+                        with self._lock:
+                            self.stats["hits"] += 1
+                            data = json.loads(row["response_json"])
+                            tokens = row["tokens_estimate"]
+                            self.stats["tokens_saved"] += tokens
+                            self._promote_lru(fingerprint, data, tokens, created_at=entry_created_at)
+                        return data
+        except Exception as err:
+            logger.warning("Cache lookup error for %s: %s", fingerprint, err)
+
+        with self._lock:
+            self.stats["misses"] += 1
+        return None
+
+    def put(self, fingerprint: str, model: str, response_data: Dict[str, Any], input_tokens_estimate: int) -> None:
+        now = time.time()
+        try:
+            raw_json = json.dumps(response_data, separators=(",", ":"))
+            with self._get_connection() as conn:
+                conn.execute("""
+                    INSERT OR REPLACE INTO evaluation_cache (
+                        fingerprint, model, response_json, created_at, hit_count, tokens_estimate
+                    ) VALUES (?, ?, ?, ?, COALESCE((SELECT hit_count FROM evaluation_cache WHERE fingerprint = ?), 0), ?)
+                """, (fingerprint, model, raw_json, now, fingerprint, input_tokens_estimate))
+                if self.ttl_seconds > 0:
+                    conn.execute("DELETE FROM evaluation_cache WHERE created_at < ?", (now - self.ttl_seconds,))
+                conn.commit()
+
+            with self._lock:
+                if self.ttl_seconds > 0:
+                    expired_keys = [k for k, v in self._memory_lru.items() if (now - v.get("created_at", 0.0)) > self.ttl_seconds]
+                    for k in expired_keys:
+                        del self._memory_lru[k]
+                self._promote_lru(fingerprint, response_data, input_tokens_estimate, created_at=now)
+        except Exception as err:
+            logger.warning("Cache store error for %s: %s", fingerprint, err)
+
+    def _promote_lru(self, fingerprint: str, data: Dict[str, Any], tokens_estimate: int, created_at: Optional[float] = None) -> None:
+        if fingerprint in self._memory_lru:
+            existing = self._memory_lru.pop(fingerprint)
+            hit_count = existing.get("hit_count", 0) + 1
+            entry_time = existing.get("created_at", created_at or time.time())
+        else:
+            hit_count = 0
+            entry_time = created_at or time.time()
+
+        if len(self._memory_lru) >= self.max_memory_items:
+            oldest_key = next(iter(self._memory_lru))
+            del self._memory_lru[oldest_key]
+        self._memory_lru[fingerprint] = {
+            "data": data,
+            "tokens_estimate": tokens_estimate,
+            "hit_count": hit_count,
+            "created_at": entry_time
+        }
+
+    def clear(self) -> None:
+        with self._lock:
+            self._memory_lru.clear()
+            self.stats["hits"] = 0
+            self.stats["misses"] = 0
+            self.stats["tokens_saved"] = 0
+        try:
+            with self._get_connection() as conn:
+                conn.execute("DELETE FROM evaluation_cache")
+                conn.commit()
+        except Exception as err:
+            logger.warning("Cache clear error: %s", err)
+
+    def get_stats(self) -> Dict[str, Any]:
+        with self._lock:
+            total = self.stats["hits"] + self.stats["misses"]
+            rate = round((self.stats["hits"] / total) * 100, 2) if total > 0 else 0.0
+            return {
+                "hits": self.stats["hits"],
+                "misses": self.stats["misses"],
+                "hit_rate_pct": rate,
+                "tokens_saved": self.stats["tokens_saved"]
+            }
+
+    def close(self) -> None:
+        with self._lock:
+            if self._shared_conn is not None:
+                try:
+                    self._shared_conn.close()
+                except Exception:
+                    pass
+                self._shared_conn = None
+            conn = getattr(self._local, "conn", None)
+            if conn is not None:
+                try:
+                    conn.close()
+                except Exception:
+                    pass
+                self._local.conn = None
+
+    def __del__(self) -> None:
+        self.close()
+
+
+SemanticCache = DeterministicCache

jevguard/calibrator.py

@@ -0,0 +1,262 @@
+"""
+jevguard.calibrator - Certainty and Dispersion Analyzer for TypeSafe AI / Jev.
+Identifies low confidence (< 0.40) and flat probability distributions (gap < 0.15),
+marking results as AMBIGUOUS_STATE to prevent false certainty.
+"""
+
+import math
+from typing import Any, Dict, List, Optional, Tuple
+
+
+class ResponseCalibrator:
+    """Evaluates probability spread on Jev decisions."""
+
+    MIN_TOP_PROBABILITY: float = 0.40
+    MIN_DISPERSION_GAP: float = 0.15
+    DEFAULT_NOUL_UNCERTAINTY_MARGIN: float = 0.12
+
+    def __init__(
+        self,
+        min_top_prob: float = MIN_TOP_PROBABILITY,
+        min_dispersion_gap: float = MIN_DISPERSION_GAP,
+        noul_uncertainty_margin: float = DEFAULT_NOUL_UNCERTAINTY_MARGIN
+    ):
+        self.min_top_prob = min_top_prob
+        self.min_dispersion_gap = min_dispersion_gap
+        self.noul_margin = noul_uncertainty_margin
+
+    def calibrate(self, raw_answers: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+        calibrated: Dict[str, Any] = {}
+        ambiguous_questions: List[str] = []
+
+        for name, ans in raw_answers.items():
+            if not isinstance(ans, dict):
+                calibrated[name] = {
+                    "is_ambiguous": True,
+                    "status": "AMBIGUOUS_STATE",
+                    "calibration": {"reasons": ["invalid_answer_structure"]},
+                    "raw": ans
+                }
+                ambiguous_questions.append(name)
+                continue
+
+            item = dict(ans)
+            q_type = str(item.get("type", "")).strip().lower()
+
+            if q_type == "choice":
+                self._calibrate_choice(item)
+            elif q_type == "score":
+                self._calibrate_score(item)
+            elif q_type == "noul":
+                self._calibrate_noul(item)
+            else:
+                item["is_ambiguous"] = True
+                item["status"] = "AMBIGUOUS_STATE"
+                item["calibration"] = {
+                    "reasons": ["unknown_question_type"],
+                    "question_type": q_type
+                }
+
+            if item.get("is_ambiguous", False):
+                ambiguous_questions.append(name)
+
+            calibrated[name] = item
+
+        summary = {
+            "total_evaluated": len(calibrated),
+            "ambiguous_count": len(ambiguous_questions),
+            "ambiguous_questions": ambiguous_questions,
+            "has_ambiguity": len(ambiguous_questions) > 0,
+            "verdict": "AMBIGUOUS_STATE" if ambiguous_questions else "CONFIDENT"
+        }
+
+        return calibrated, summary
+
+    def _calibrate_choice(self, item: Dict[str, Any]) -> None:
+        probs = item.get("probabilities", {})
+        parsed_pairs: List[Tuple[str, float]] = []
+        has_invalid = False
+        if isinstance(probs, dict):
+            for k, v in probs.items():
+                try:
+                    val = float(v)
+                    if math.isnan(val) or math.isinf(val):
+                        has_invalid = True
+                    else:
+                        parsed_pairs.append((str(k), val))
+                except (ValueError, TypeError):
+                    has_invalid = True
+
+        if not parsed_pairs:
+            try:
+                raw_conf = item.get("confidence", 0.0)
+                conf = float(raw_conf)
+                if math.isnan(conf) or math.isinf(conf):
+                    conf = 0.0
+                    has_invalid = True
+            except (ValueError, TypeError):
+                conf = 0.0
+                has_invalid = True
+
+            reasons = []
+            if has_invalid:
+                reasons.append("invalid_probability")
+            if conf < self.min_top_prob:
+                reasons.append("low_confidence")
+
+            is_amb = len(reasons) > 0
+            item["is_ambiguous"] = is_amb
+            item["status"] = "AMBIGUOUS_STATE" if is_amb else "CONFIDENT"
+            item["calibration"] = {
+                "top_choice": item.get("choice"),
+                "top_probability": round(conf, 4),
+                "runner_up_choice": None,
+                "runner_up_probability": 0.0,
+                "dispersion_gap": round(conf, 4),
+                "reasons": reasons
+            }
+            return
+
+        sorted_pairs = sorted(parsed_pairs, key=lambda x: x[1], reverse=True)
+        top_k, top_p = sorted_pairs[0]
+        runner_k, runner_p = sorted_pairs[1] if len(sorted_pairs) > 1 else (None, 0.0)
+        gap = top_p - runner_p
+
+        reasons = []
+        if has_invalid:
+            reasons.append("invalid_probability")
+        if top_p < self.min_top_prob:
+            reasons.append("low_confidence")
+        if len(sorted_pairs) > 1 and gap < self.min_dispersion_gap:
+            reasons.append("flat_distribution")
+
+        is_amb = len(reasons) > 0
+        item["is_ambiguous"] = is_amb
+        item["status"] = "AMBIGUOUS_STATE" if is_amb else "CONFIDENT"
+        item["calibration"] = {
+            "top_choice": top_k,
+            "top_probability": round(top_p, 4),
+            "runner_up_choice": runner_k,
+            "runner_up_probability": round(runner_p, 4),
+            "dispersion_gap": round(gap, 4),
+            "reasons": reasons
+        }
+
+    def _calibrate_score(self, item: Dict[str, Any]) -> None:
+        reasons: List[str] = []
+        raw_conf = item.get("confidence")
+        if raw_conf is None:
+            conf = 0.0
+            reasons.append("low_confidence")
+        else:
+            try:
+                conf = float(raw_conf)
+                if math.isnan(conf) or math.isinf(conf):
+                    conf = 0.0
+                    reasons.append("invalid_probability")
+            except (ValueError, TypeError):
+                conf = 0.0
+                reasons.append("invalid_probability")
+
+        probs = item.get("probabilities", {})
+
+        if conf < self.min_top_prob and "low_confidence" not in reasons:
+            reasons.append("low_confidence")
+
+        dispersion_gap = conf
+        if isinstance(probs, dict) and len(probs) >= 2:
+            parsed_probs: List[float] = []
+            for v in probs.values():
+                try:
+                    val = float(v)
+                    if math.isnan(val) or math.isinf(val):
+                        if "invalid_probability" not in reasons:
+                            reasons.append("invalid_probability")
+                    else:
+                        parsed_probs.append(val)
+                except (ValueError, TypeError):
+                    if "invalid_probability" not in reasons:
+                        reasons.append("invalid_probability")
+            if len(parsed_probs) >= 2:
+                sorted_probs = sorted(parsed_probs, reverse=True)
+                top_p = sorted_probs[0]
+                runner_p = sorted_probs[1]
+                dispersion_gap = top_p - runner_p
+                if top_p < self.min_top_prob and "low_confidence" not in reasons:
+                    reasons.append("low_confidence")
+                if dispersion_gap < self.min_dispersion_gap and "flat_distribution" not in reasons:
+                    reasons.append("flat_distribution")
+
+        is_amb = len(reasons) > 0
+        item["is_ambiguous"] = is_amb
+        item["status"] = "AMBIGUOUS_STATE" if is_amb else "CONFIDENT"
+        item["calibration"] = {
+            "confidence": round(conf, 4),
+            "dispersion_gap": round(dispersion_gap, 4),
+            "reasons": reasons
+        }
+
+    def _calibrate_noul(self, item: Dict[str, Any]) -> None:
+        val = item.get("noul")
+        if val is None:
+            item["is_ambiguous"] = True
+            item["status"] = "AMBIGUOUS_STATE"
+            item["calibration"] = {
+                "probability": 0.0,
+                "boundary_distance": 0.0,
+                "reasons": ["missing_noul_value"]
+            }
+            return
+        try:
+            prob = float(val)
+        except (ValueError, TypeError):
+            item["is_ambiguous"] = True
+            item["status"] = "AMBIGUOUS_STATE"
+            item["calibration"] = {
+                "probability": 0.0,
+                "boundary_distance": 0.0,
+                "reasons": ["invalid_probability"]
+            }
+            return
+
+        if math.isnan(prob) or math.isinf(prob):
+            item["is_ambiguous"] = True
+            item["status"] = "AMBIGUOUS_STATE"
+            item["calibration"] = {
+                "probability": 0.0,
+                "boundary_distance": 0.0,
+                "reasons": ["invalid_probability"]
+            }
+            return
+
+        dist = abs(prob - 0.50)
+        is_amb = dist < self.noul_margin
+
+        item["is_ambiguous"] = is_amb
+        item["status"] = "AMBIGUOUS_STATE" if is_amb else "CONFIDENT"
+        item["calibration"] = {
+            "probability": round(prob, 4),
+            "boundary_distance": round(dist, 4),
+            "reasons": ["boundary_uncertainty"] if is_amb else []
+        }
+
+    def calibrate_choice(self, item: Dict[str, Any]) -> Dict[str, Any]:
+        """Convenience method to calibrate a single choice answer dictionary in-place."""
+        c = dict(item)
+        self._calibrate_choice(c)
+        return c
+
+    def calibrate_score(self, item: Dict[str, Any]) -> Dict[str, Any]:
+        """Convenience method to calibrate a single score answer dictionary in-place."""
+        s = dict(item)
+        self._calibrate_score(s)
+        return s
+
+    def calibrate_noul(self, item: Dict[str, Any]) -> Dict[str, Any]:
+        """Convenience method to calibrate a single noul answer dictionary in-place."""
+        n = dict(item)
+        self._calibrate_noul(n)
+        return n
+
+
+CertaintyCalibrator = ResponseCalibrator