semanticmemo 1.2.0__py3-none-any.whl

semanticmemo/__init__.py

@@ -0,0 +1,48 @@
+"""SemanticMemo public API."""
+
+__version__ = "1.0.0"
+
+
+from semanticmemo import _logging as _logging  # noqa: F401  (installs the NullHandler)
+from semanticmemo.cache import SemanticMemo
+from semanticmemo.entity_change_detection import EntityChangeConfig, EntityChangeResult
+from semanticmemo.feedback import RetrainConfig, RetrainResult, retrain_from_feedback
+from semanticmemo.models import (
+    CacheConfig,
+    CacheDecision,
+    CacheEntry,
+    CacheResult,
+    CacheStats,
+    ClassifierConfig,
+    CrossEncoderConfig,
+    EvictionPolicy,
+    FeedbackEvent,
+    ImplicitFeedbackConfig,
+    LookupRecord,
+    RetryConfig,
+    RiskPolicy,
+    RiskTier,
+)
+
+__all__ = [
+    "CacheConfig",
+    "CacheDecision",
+    "CacheEntry",
+    "CacheResult",
+    "CacheStats",
+    "ClassifierConfig",
+    "SemanticMemo",
+    "EntityChangeConfig",
+    "EntityChangeResult",
+    "EvictionPolicy",
+    "FeedbackEvent",
+    "ImplicitFeedbackConfig",
+    "LookupRecord",
+    "RetrainConfig",
+    "RetrainResult",
+    "RetryConfig",
+    "CrossEncoderConfig",
+    "RiskPolicy",
+    "RiskTier",
+    "retrain_from_feedback",
+]

semanticmemo/_logging.py

@@ -0,0 +1,29 @@
+"""Internal logging setup.
+
+SemanticMemo is a library, so it is silent by default: it attaches a single
+``logging.NullHandler`` to the ``SemanticMemo`` parent logger and never configures
+handlers or levels itself. An application that wants to see SemanticMemo logs opts
+in explicitly, e.g.::
+
+    import logging
+    logging.basicConfig(level=logging.INFO)
+    logging.getLogger("semanticmemo").setLevel(logging.DEBUG)
+"""
+
+from __future__ import annotations
+
+import logging
+
+# Installed once, at import time, on the package's root logger. Child loggers
+# (``SemanticMemo.orchestrator`` etc.) propagate to it, so this single handler
+# keeps the whole library quiet unless the application configures logging.
+logging.getLogger("semanticmemo").addHandler(logging.NullHandler())
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a logger under the ``SemanticMemo`` namespace.
+
+    Call as ``get_logger(__name__)`` from within the package so the logger name
+    is, for example, ``SemanticMemo.store.sqlite_store``.
+    """
+    return logging.getLogger(name)

semanticmemo/_models/equivalence-net-v1.report.json

@@ -0,0 +1,248 @@
+{
+  "architecture": "PairClassifier MLP over [a, b, |a-b|, a*b] -> 128 -> 64 -> 1",
+  "created_at": "2026-05-20T11:05:06.857011+00:00",
+  "dataset_manifest": {
+    "corpus": {
+      "action_templates": 109,
+      "base_prompts": 96
+    },
+    "generated_at": "2026-05-20T10:58:01.768234+00:00",
+    "hard_neg_per_template": 10,
+    "model": "qwen3:8b",
+    "n_para_base": 6,
+    "n_para_template": 4,
+    "neg_ratio": 1.0,
+    "ollama_host": "http://localhost:11434",
+    "seed": 7,
+    "train": {
+      "negatives": 6788,
+      "opposite_action": 1800,
+      "paraphrase": 6788,
+      "positives": 6788,
+      "total": 13576,
+      "unrelated": 4988
+    },
+    "train_ratio": 0.8,
+    "validation": {
+      "negatives": 1500,
+      "opposite_action": 380,
+      "paraphrase": 1500,
+      "positives": 1500,
+      "total": 3000,
+      "unrelated": 1120
+    }
+  },
+  "embedding_dim": 384,
+  "embedding_model": "sentence-transformers/all-MiniLM-L6-v2",
+  "gold_metrics": {
+    "accuracy": 0.9047619047619048,
+    "auc_roc": 0.963481436396835,
+    "examples": 84,
+    "expected_calibration_error": 0.10387316706627754,
+    "f1": 0.8787878787878788,
+    "false_negatives": 2,
+    "false_positives": 6,
+    "precision": 0.8285714285714286,
+    "recall": 0.9354838709677419,
+    "threshold": 0.95,
+    "true_negatives": 47,
+    "true_positives": 29
+  },
+  "gold_threshold_sweep": [
+    {
+      "f1": 0.8788,
+      "precision": 0.8286,
+      "recall": 0.9355,
+      "threshold": 0.5
+    },
+    {
+      "f1": 0.8788,
+      "precision": 0.8286,
+      "recall": 0.9355,
+      "threshold": 0.7
+    },
+    {
+      "f1": 0.8788,
+      "precision": 0.8286,
+      "recall": 0.9355,
+      "threshold": 0.8
+    },
+    {
+      "f1": 0.8788,
+      "precision": 0.8286,
+      "recall": 0.9355,
+      "threshold": 0.85
+    },
+    {
+      "f1": 0.8788,
+      "precision": 0.8286,
+      "recall": 0.9355,
+      "threshold": 0.9
+    },
+    {
+      "f1": 0.8788,
+      "precision": 0.8286,
+      "recall": 0.9355,
+      "threshold": 0.95
+    }
+  ],
+  "gold_vs_cosine": {
+    "classifier": {
+      "accuracy": 0.9047619047619048,
+      "auc_roc": 0.963481436396835,
+      "examples": 84,
+      "expected_calibration_error": 0.10387316706627754,
+      "f1": 0.8787878787878788,
+      "false_negatives": 2,
+      "false_positives": 6,
+      "precision": 0.8285714285714286,
+      "recall": 0.9354838709677419,
+      "threshold": 0.95,
+      "true_negatives": 47,
+      "true_positives": 29
+    },
+    "cosine_at_classifier_recall": {
+      "accuracy": 0.6666666666666666,
+      "auc_roc": 0.790626902008521,
+      "examples": 84,
+      "expected_calibration_error": 0.2644111977202729,
+      "f1": 0.6744186046511628,
+      "false_negatives": 2,
+      "false_positives": 26,
+      "precision": 0.5272727272727272,
+      "recall": 0.9354838709677419,
+      "target_recall": 0.9354838709677419,
+      "threshold": 0.72,
+      "true_negatives": 27,
+      "true_positives": 29
+    },
+    "cosine_default": {
+      "accuracy": 0.7023809523809523,
+      "auc_roc": 0.790626902008521,
+      "examples": 84,
+      "expected_calibration_error": 0.2644111977202729,
+      "f1": 0.4897959183673469,
+      "false_negatives": 19,
+      "false_positives": 6,
+      "precision": 0.6666666666666666,
+      "recall": 0.3870967741935484,
+      "threshold": 0.9,
+      "true_negatives": 47,
+      "true_positives": 12
+    },
+    "examples": 84,
+    "gate_passed": true,
+    "gold_path": "data/gold/equivalence_gold.jsonl",
+    "model_path": "src/semanticmemo/_models/equivalence-net-v1.pt",
+    "negatives": 53,
+    "positives": 31,
+    "precision_gain_at_equal_recall": 0.3012987012987014
+  },
+  "high_stakes": {
+    "classifier": {
+      "accuracy": 0.6785714285714286,
+      "auc_roc": 0.7239583333333334,
+      "examples": 28,
+      "expected_calibration_error": 0.3770394833700834,
+      "f1": 0.6666666666666665,
+      "false_negatives": 3,
+      "false_positives": 6,
+      "precision": 0.6,
+      "recall": 0.75,
+      "threshold": 0.95,
+      "true_negatives": 10,
+      "true_positives": 9
+    },
+    "classifier_false_positives": 6,
+    "classifier_threshold": 0.95,
+    "cosine": {
+      "accuracy": 0.42857142857142855,
+      "auc_roc": 0.328125,
+      "examples": 28,
+      "expected_calibration_error": 0.5026936094675745,
+      "f1": 0.3333333333333333,
+      "false_negatives": 8,
+      "false_positives": 8,
+      "precision": 0.3333333333333333,
+      "recall": 0.3333333333333333,
+      "threshold": 0.9,
+      "true_negatives": 8,
+      "true_positives": 4
+    },
+    "cosine_false_positives": 8,
+    "cosine_threshold": 0.9,
+    "dangerous_hits_blocked_by_classifier": 4,
+    "data_path": "benchmarks/data/high_stakes_pairs.jsonl",
+    "examples": 28,
+    "model_path": "src/semanticmemo/_models/equivalence-net-v1.pt",
+    "negatives": 16,
+    "positives": 12
+  },
+  "limitations": "Trained on LLM-paraphrased and templated data across nine domains (customer-support, software-engineering, scheduling, data-analysis, devops, general-qa, medical, legal, finance). It is a generic cold-start model: per-domain accuracy improves with the `semanticmemo retrain` feedback loop. Bound to the all-MiniLM-L6-v2 embedding space (384-dim).",
+  "model": "equivalence-net-v1",
+  "operating_threshold": 0.95,
+  "scope": "generic cross-domain cold-start classifier (nine domains)",
+  "training": {
+    "batch_size": 64,
+    "dropout": 0.2,
+    "epochs": 15,
+    "final_train_loss": 0.024864289640151666,
+    "learning_rate": 0.001,
+    "seed": 7,
+    "train_examples": 13576,
+    "validation_examples": 3000
+  },
+  "validation_metrics": {
+    "accuracy": 0.9056666666666666,
+    "auc_roc": 0.9745157777777778,
+    "examples": 3000,
+    "expected_calibration_error": 0.07148537254798411,
+    "f1": 0.9028492962581531,
+    "false_negatives": 185,
+    "false_positives": 98,
+    "precision": 0.9306440198159943,
+    "recall": 0.8766666666666667,
+    "threshold": 0.95,
+    "true_negatives": 1402,
+    "true_positives": 1315
+  },
+  "validation_threshold_sweep": [
+    {
+      "f1": 0.9113,
+      "precision": 0.8952,
+      "recall": 0.928,
+      "threshold": 0.5
+    },
+    {
+      "f1": 0.9155,
+      "precision": 0.9103,
+      "recall": 0.9207,
+      "threshold": 0.7
+    },
+    {
+      "f1": 0.9138,
+      "precision": 0.9162,
+      "recall": 0.9113,
+      "threshold": 0.8
+    },
+    {
+      "f1": 0.9105,
+      "precision": 0.9192,
+      "recall": 0.902,
+      "threshold": 0.85
+    },
+    {
+      "f1": 0.9094,
+      "precision": 0.9261,
+      "recall": 0.8933,
+      "threshold": 0.9
+    },
+    {
+      "f1": 0.9028,
+      "precision": 0.9306,
+      "recall": 0.8767,
+      "threshold": 0.95
+    }
+  ]
+}
+

semanticmemo/cache.py

@@ -0,0 +1,149 @@
+"""Public cache facade."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from semanticmemo._logging import get_logger
+from semanticmemo.classifier import ClassifierService, CrossEncoderService
+from semanticmemo.domain_detector import DomainDetector
+from semanticmemo.embedding import (
+    EmbeddingService,
+    FaissVectorIndex,
+    InMemoryVectorIndex,
+    SentenceTransformerEmbeddingProvider,
+)
+from semanticmemo.entity_change_detection import EntityChangeConfig
+from semanticmemo.exceptions import MissingDependencyError
+from semanticmemo.models import CacheConfig, CacheResult, CacheStats, ClassifierConfig
+from semanticmemo.orchestrator import CacheOrchestrator
+from semanticmemo.store import SQLiteCacheStore
+from semanticmemo.types import EmbeddingProvider, LLMFunction
+
+logger = get_logger(__name__)
+
+
+class SemanticMemo:
+    """Async-first semantic cache facade.
+
+    Without a classifier checkpoint, SemanticMemo uses cosine similarity as a
+    measured baseline. With a classifier checkpoint, cosine search selects
+    candidates and the learned classifier decides cache hits.
+    """
+
+    def __init__(
+        self,
+        *,
+        domain: str,
+        config: CacheConfig | None = None,
+        embedding_provider: EmbeddingProvider | None = None,
+        classifier: ClassifierConfig | None = None,
+        store: SQLiteCacheStore | None = None,
+        use_faiss: bool = True,
+        entity_change_config: EntityChangeConfig | None = None,
+    ) -> None:
+        self.domain = domain
+        self.config = config or CacheConfig()
+        self.store = store or SQLiteCacheStore(self.config.db_path)
+        provider = embedding_provider or SentenceTransformerEmbeddingProvider(
+            self.config.embedding_model,
+            dim=self.config.embedding_dim,
+        )
+        if use_faiss:
+            try:
+                index = FaissVectorIndex(provider.dim)
+            except MissingDependencyError as exc:
+                logger.warning("faiss unavailable, falling back to InMemoryVectorIndex: %s", exc)
+                index = InMemoryVectorIndex(provider.dim)
+        else:
+            index = InMemoryVectorIndex(provider.dim)
+        embedding_service = EmbeddingService(provider, index)
+        classifier_service = self._build_classifier_service(classifier)
+        cross_encoder_service = self._build_cross_encoder_service()
+        domain_detector = self._build_domain_detector(embedding_service)
+        self._orchestrator = CacheOrchestrator(
+            domain=domain,
+            config=self.config,
+            store=self.store,
+            embedding_service=embedding_service,
+            classifier_service=classifier_service,
+            cross_encoder_service=cross_encoder_service,
+            domain_detector=domain_detector,
+            entity_change_config=entity_change_config,
+        )
+
+    async def get_or_call(
+        self,
+        *,
+        prompt: str,
+        llm_function: LLMFunction,
+        model: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> CacheResult:
+        return await self._orchestrator.get_or_call(
+            prompt=prompt,
+            llm_function=llm_function,
+            model=model,
+            metadata=metadata,
+        )
+
+    async def report_bad_hit(self, query_id: UUID, reason: str | None = None) -> bool:
+        return self._orchestrator.report_bad_hit(query_id, reason=reason)
+
+    async def report_good_hit(self, query_id: UUID) -> bool:
+        return self._orchestrator.report_good_hit(query_id)
+
+    def stats(self) -> CacheStats:
+        return self._orchestrator.stats()
+
+    def export_feedback_pairs(self, path: Path | str, *, split: str = "train") -> int:
+        return self._orchestrator.export_feedback_pairs(str(path), split=split)
+
+    def export_active_learning_pairs(self, path: Path | str, *, split: str = "train") -> int:
+        return self.store.export_active_learning_pairs(str(path), split=split)
+
+    def close(self) -> None:
+        """Close the underlying store. Safe to call more than once."""
+        self.store.close()
+        logger.debug("SemanticMemo closed: domain=%s", self.domain)
+
+    async def __aenter__(self) -> SemanticMemo:
+        """Enter an ``async with`` block; returns this instance."""
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        """Exit an ``async with`` block, closing the store. Exceptions propagate."""
+        self.close()
+
+    def _build_classifier_service(
+        self,
+        classifier: ClassifierConfig | None,
+    ) -> ClassifierService | None:
+        if classifier is None or classifier.model_path is None:
+            return None
+        threshold = (
+            classifier.threshold
+            if classifier.threshold is not None
+            else self.config.classifier_threshold
+        )
+        return ClassifierService(
+            classifier.model_path,
+            device=classifier.device,
+            threshold=threshold,
+        )
+
+    def _build_cross_encoder_service(self) -> CrossEncoderService | None:
+        if self.config.cross_encoder is None:
+            return None
+        return CrossEncoderService(
+            model_name=self.config.cross_encoder.model_name,
+            device=self.config.cross_encoder.device,
+            threshold=self.config.cross_encoder.threshold,
+        )
+
+    def _build_domain_detector(self, embedding_service: EmbeddingService) -> DomainDetector | None:
+        if self.config.risk_policy is None:
+            return None
+        return DomainDetector(embedding_service)

semanticmemo/classifier/__init__.py

@@ -0,0 +1,28 @@
+"""Classifier training and inference utilities."""
+
+from semanticmemo.classifier.cross_encoder_service import CrossEncoderService
+from semanticmemo.classifier.data import EmbeddedPairDataset, PairRecord, load_pair_records
+from semanticmemo.classifier.evaluate import (
+    EvaluationMetrics,
+    compute_binary_metrics,
+    evaluate_model,
+)
+from semanticmemo.classifier.model import PairClassifier, build_pair_features
+from semanticmemo.classifier.service import ClassifierService
+from semanticmemo.classifier.train import TrainingConfig, TrainingResult, train_classifier
+
+__all__ = [
+    "ClassifierService",
+    "CrossEncoderService",
+    "EmbeddedPairDataset",
+    "EvaluationMetrics",
+    "PairClassifier",
+    "PairRecord",
+    "TrainingConfig",
+    "TrainingResult",
+    "build_pair_features",
+    "compute_binary_metrics",
+    "evaluate_model",
+    "load_pair_records",
+    "train_classifier",
+]

semanticmemo/classifier/cross_encoder_service.py

@@ -0,0 +1,84 @@
+"""Inference wrapper for second-stage Cross-Encoder models."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+
+from sentence_transformers import CrossEncoder
+
+from semanticmemo._logging import get_logger
+
+logger = get_logger(__name__)
+
+# Global cache for instantiated CrossEncoder models to avoid reloading overhead
+_MODEL_CACHE: dict[tuple[str, str], CrossEncoder] = {}
+
+
+class CrossEncoderService:
+    """Wrapper around sentence-transformers CrossEncoder for high-precision validation."""
+
+    def __init__(
+        self,
+        model_name: str = "cross-encoder/ms-marco-MiniLM-L-6-v2",
+        *,
+        device: str = "cpu",
+        threshold: float | None = None,
+    ) -> None:
+        self.model_name = model_name
+        self.device = device
+        self.threshold = threshold
+        self._model: CrossEncoder | None = None
+
+    @property
+    def model(self) -> CrossEncoder:
+        if self._model is None:
+            cache_key = (self.model_name, self.device)
+            if cache_key in _MODEL_CACHE:
+                self._model = _MODEL_CACHE[cache_key]
+            else:
+                logger.info("Loading CrossEncoder: %s on %s", self.model_name, self.device)
+                self._model = CrossEncoder(self.model_name, device=self.device)
+                _MODEL_CACHE[cache_key] = self._model
+        return self._model
+
+    def predict(self, prompt_a: str, prompt_b: str) -> float:
+        """Score a single pair of prompts."""
+        return self.predict_batch([(prompt_a, prompt_b)])[0]
+
+    def predict_batch(self, pairs: Sequence[tuple[str, str]]) -> list[float]:
+        """Score a list of prompt pairs.
+
+        Returns probability scores mapped to [0, 1] using sigmoid.
+        """
+        if not pairs:
+            return []
+
+        # Convert sequence to list of lists/tuples as expected by sentence-transformers
+        formatted_pairs = [list(pair) for pair in pairs]
+
+        # Run prediction
+        raw_scores = self.model.predict(formatted_pairs, show_progress_bar=False)
+
+        # Handle single float vs list output
+        if isinstance(raw_scores, (int, float)):
+            raw_scores = [raw_scores]
+
+        # Apply sigmoid because ms-marco output is a logit, but we need [0, 1] probability
+        # Also handle potential NaN or infinity safely
+        probs = []
+        for score in raw_scores:
+            s = float(score)
+            # sigmoid(x) = 1 / (1 + exp(-x))
+            try:
+                prob = 1.0 / (1.0 + math.exp(-s))
+            except OverflowError:
+                prob = 0.0 if s < 0 else 1.0
+            probs.append(prob)
+
+        return probs
+
+    def is_equivalent(self, prompt_a: str, prompt_b: str) -> bool:
+        """Check if two prompts are equivalent based on the threshold."""
+        threshold = 0.90 if self.threshold is None else self.threshold
+        return self.predict(prompt_a, prompt_b) >= threshold