semanticmemo 1.2.0__tar.gz

semanticmemo-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    name: Test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "${{ matrix.python-version }}"
+
+      - name: Install dependencies
+        run: uv sync --all-extras --frozen
+
+      - name: Check formatting
+        run: uv run ruff format --check
+
+      - name: Lint
+        run: uv run ruff check
+
+      - name: Type check
+        run: uv run pyright
+
+      - name: Test
+        run: uv run pytest

semanticmemo-1.2.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,84 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Test before publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras --frozen
+
+      - name: Check formatting
+        run: uv run ruff format --check
+
+      - name: Lint
+        run: uv run ruff check
+
+      - name: Type check
+        run: uv run pyright
+
+      - name: Test
+        run: uv run pytest
+
+  build:
+    name: Build distributions
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish distributions to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/semanticmemo
+    permissions:
+      actions: read
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

semanticmemo-1.2.0/.gitignore

@@ -0,0 +1,21 @@
+.DS_Store
+.venv/
+.ruff_cache/
+.pytest_cache/
+.pyright/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.coverage
+htmlcov/
+*.db
+*.sqlite
+*.sqlite3
+models/*.pt
+!models/.gitkeep
+data/generated/
+data/training/.paraphrase_cache.json
+scratch/
+

semanticmemo-1.2.0/AGENTS.md

@@ -0,0 +1,232 @@
+# AGENTS.md — SemanticMemo Project Guide
+
+> **Author & Lead Engineer:** Rajveer Singh Saggu  
+> **Repository:** [rajveer100704/semanticmemo](https://github.com/rajveer100704/semanticmemo)  
+> This guide is the single source of truth for the SemanticMemo project. It documents the ML rationale, systems architecture, and engineering principles behind this learned semantic caching layer.
+
+---
+
+## The Philosophy & Vision
+
+### Why Cosine Similarity Fails in Production
+Semantic caching is essential for scaling LLM applications. However, existing industry solutions (like GPTCache) rely on a naive cosine similarity threshold in embedding space. In my work, I realized a foundational truth:
+
+**Cosine similarity is not equivalence.**
+
+In embedding space, prompts asking for opposite actions can sit extremely close. For example, *"Should I accept this meeting request?"* and *"Should I reject this meeting request?"* have a cosine similarity of ~0.97 using standard sentence encoders. A naive cache treats them as equivalent and serves the cached answer of one to the other.
+
+In critical domains like finance, healthcare, or security, this is not just a cheap cache hit — it is a silent, catastrophic bug. It is a false-positive that returns wrong data to an agent, prompting incorrect actions.
+
+### The SemanticMemo Solution
+SemanticMemo replaces the arbitrary, static cosine threshold with a **learned equivalence classifier** fine-tuned on domain-specific prompt traces. By modeling semantic equivalence as a supervised matching problem, it distinguishes intent from surface similarity.
+
+**The Vision:**
+> Providing a highly reliable, domain-adapted semantic cache that teams can confidently run in production. Cache hit rates of 60-80% with classifier-validated correctness, preventing silent bugs and keeping LLM operating costs predictable.
+
+---
+
+## The Problem in Concrete Terms
+
+When building real-world AI agents, developers are forced into two compromises:
+- **No Caching:** Every query hits the LLM API. High latency, high API costs, and linear scaling with traffic.
+- **Naive Cosine Caching:** Fast and cheap, but high false-positive rates (FPR). The agent receives cached responses to different prompts, leading to incorrect actions that are notoriously hard to debug.
+
+SemanticMemo introduces a third option: **Double-Verification Caching**. It combines fast vector retrieval with a high-precision, low-latency classifier to ensure only functionally equivalent prompts trigger cache hits.
+
+---
+
+## The Mental Model: A Multi-Stage Verification Pipeline
+
+SemanticMemo works like a layered security checkpoint:
+1. **Metal Detector (High Recall, Low Latency):** Uses fast vector similarity (FAISS / Qdrant) to quickly retrieve the top $K$ candidates ($O(\log N)$).
+2. **First Gate (MLP Classifier):** Evaluates candidate pairs via a fast (~1ms) classifier ($O(K)$). If the score is extremely high (e.g. $\ge 0.995$), it bypasses the next gate.
+3. **Second Gate (Cross-Encoder):** Runs a deep joint-attention transformer pass on candidate pairs where the MLP is uncertain, providing high-precision validation.
+4. **Final Gate (Entity Change Detector):** Runs a zero-latency (<1ms) battery of 11 regex detectors to veto any matches that contain critical entity drift (e.g. quarter, drug, year, numeric, or proper noun changes).
+
+This structure ensures both sub-millisecond retrieval scaling and maximum correctness in production.
+
+---
+
+## Core Architecture
+
+The codebase is structured around five core concepts:
+
+### 1. The Embedding Layer (Fast Filter)
+Embeds incoming queries and queries the vector index (FAISS or Qdrant) for the top $K$ candidate vectors.
+- **Default Encoder:** `sentence-transformers/all-MiniLM-L6-v2` (384-dimensional).
+- **Index:** `faiss.IndexFlatIP` (normalized inner product for cosine similarity).
+
+### 2. The Equivalence Classifier (Stage 1 MLP)
+A lightweight neural network computing equivalence probabilities on concatenated features ($[u, v, |u - v|, u * v]$).
+- **Architecture:** MLP head with 2 hidden layers (128 → 64 → 1) and ReLU activation.
+- **Inference Latency:** < 1.5ms on CPU.
+
+### 3. The Cross-Encoder (Stage 2 Re-ranker)
+A transformer-based cross-encoder (`cross-encoder/ms-marco-MiniLM-L-6-v2`) that parses joint-attention representations.
+- **Domain Tuning:** Thresholds are dynamically conditioned per domain (Medical, Finance, Security, Customer Support).
+- **Latency Optimization:** Bypassed when the MLP score $\ge$ skip threshold (triggering on ~94.7% of hits).
+
+### 4. The Entity Change Detector (Stage 3 Veto)
+A battery of 11 lightweight, regex-based check rules validating key entities (e.g. Q3 vs Q4, Tesla vs Apple).
+- **Latency:** < 1ms on CPU, no ML inference.
+- **Configurability:** Fully toggleable per detector or system-wide.
+
+### 5. The Cache Store & Active Learning Ledger (Persistence)
+SQLite database managing cache storage (LRU/TTL eviction) and active learning logging.
+- **Active Learning:** Logs MLP/CE disagreements and entity-vetoed misses to `active_learning_pairs` as training data for future classifier retraining.
+
+---
+
+## Complete Request Lifecycle
+
+The diagram below outlines the cache lookup workflow:
+
+```
+agent calls semanticmemo.get_or_call(prompt, llm_function)
+    │
+    ▼
+1. embed(prompt) → query_embedding
+    │
+    ▼
+2. FAISS/Qdrant search → candidate_ids (K=5)
+    │
+    ▼
+3. Run MLP Classifier on candidates
+    ├── Score >= Skip Threshold (0.995) ──┐
+    └── Score < Skip Threshold            │
+            │                             │
+            ▼                             ▼
+       Run Cross-Encoder             [Bypass CE]
+            │                             │
+            ▼                             │
+       Verify thresholds                  │
+       (Passed?)                          │
+            ├── Yes ──────────────────────┤
+            └── No ──► Cache Miss         │
+                        │                 │
+                        ▼                 ▼
+             Store LLM response  ◄─── Run Entity Detector
+                                      (Entity Changed?)
+                                           ├── Yes (Drift) ──► Cache Miss & Log AL
+                                           └── No ───────────► Cache Hit
+```
+
+---
+
+## Public API Surface
+
+### Minimal Usage
+```python
+from semanticmemo import SemanticMemo
+from anthropic import AsyncAnthropic
+
+client = AsyncAnthropic()
+cache = SemanticMemo(domain="customer-support")
+
+async def call_llm(prompt: str) -> str:
+    response = await client.messages.create(
+        model="claude-3-5-sonnet-latest",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": prompt}],
+    )
+    return response.content[0].text
+
+# Wrapper handles cache check, lookup, decision, and LLM call fallback
+result = await cache.get_or_call(
+    prompt="List the active tickets for user 102",
+    llm_function=call_llm,
+)
+print(result.response)
+print(result.was_cache_hit)
+print(result.cost_saved_usd)
+```
+
+### Complete Configuration
+```python
+from semanticmemo import SemanticMemo, CacheConfig, ClassifierConfig, EvictionPolicy
+
+cache = SemanticMemo(
+    domain="finance",
+    config=CacheConfig(
+        embedding_dim=384,
+        candidate_k=5,
+        max_entries=5000,
+        eviction_policy=EvictionPolicy.LRU,
+        ttl_seconds=86400 * 14, # 14 days
+    ),
+    classifier=ClassifierConfig(
+        model_path="./models/equivalence-net-v1.pt",
+        device="cpu"
+    )
+)
+```
+
+---
+
+## Internal Code Structure
+
+```
+semanticmemo/
+├── src/
+│   └── semanticmemo/
+│       ├── __init__.py                # Public API exports
+│       ├── cache.py                   # Main SemanticMemo orchestrator
+│       ├── orchestrator.py            # CacheOrchestrator pipeline
+│       ├── embedding/
+│       │   ├── __init__.py
+│       │   ├── service.py             # EmbeddingService (Model + FAISS)
+│       │   └── models.py              # Embedding providers
+│       ├── classifier/
+│       │   ├── __init__.py
+│       │   ├── service.py             # ClassifierService (Inference wrapper)
+│       │   ├── model.py               # PairClassifier (PyTorch Module)
+│       │   ├── train.py               # Classifier training pipeline
+│       │   ├── data.py                # Dataset loaders and transformers
+│       │   └── evaluate.py            # Evaluation helper utilities
+│       ├── store/
+│       │   ├── __init__.py
+│       │   ├── sqlite_store.py        # SQLite CacheStore implementation
+│       │   ├── eviction.py            # Eviction policy modules
+│       │   └── schema.sql             # SQL Schema DDL
+│       ├── feedback/
+│       │   ├── __init__.py
+│       │   ├── ledger.py              # FeedbackLedger database
+│       │   └── retrain.py             # Retraining orchestration
+│       ├── stats.py                   # Cache stats collectors
+│       ├── models.py                  # Pydantic models (CacheResult, CacheDecision)
+│       ├── exceptions.py              # Custom exceptions
+│       └── cli.py                     # CLI entry points
+├── benchmarks/
+│   ├── run_benchmarks.py              # Complete suite runner
+│   ├── sweep_thresholds.py            # Threshold optimization grid-search
+│   ├── false_positive_eval.py         # Hard negative / opposite action tests
+│   ├── prompt_mutation_benchmark.py   # Mutation robustness suite
+│   └── data/                          # Benchmark datasets (.jsonl)
+├── examples/                          # Reference integration files
+├── tests/                             # Pytest suite
+└── pyproject.toml                     # Package dependencies and settings
+```
+
+---
+
+## Development History & Roadmap
+
+### Version 1.0.0 (Production Stable)
+- **Double Verification Caching:** FAISS + MLP Classifier + Cross-Encoder verification.
+- **Domain Auto-Detection:** Automatically routes queries using domain centroid distance.
+- **Risk-Aware Policies:** Allows stricter classification thresholds on sensitive domains.
+- **Performance Optimizations:** Global model caching and CPU-based warmup profiles.
+- **Full Benchmarks:** Hard negative FPR reduced from 33.3% to 0% with minimal latency overhead.
+
+### Future Enhancements
+- **pgvector & Qdrant Backends:** Support for external vector databases in distributed setups.
+- **Online Continual Learning:** Background training worker updating the classifier weights asynchronously.
+
+---
+
+## Engineering Standards
+
+1. **Typing & Validation:** Strict type annotations across all code. Run `uv run pyright` to verify types.
+2. **Silent by Default:** Library logging propagates to a root `semanticmemo` namespace using `logging.NullHandler`.
+3. **No Unmanaged Latency:** CPU inference must be optimized. Models are initialized lazily and cached globally.
+4. **Test-Driven Rigor:** Maintain >90% test coverage. Every new component must have corresponding unit tests in `tests/`.

semanticmemo-1.2.0/CHANGELOG.md

@@ -0,0 +1,183 @@
+# Changelog
+
+## 1.2.0
+
+Upgrade release featuring zero-latency entity drift protection, domain-conditioned thresholds, active learning builder, and safety-framed benchmarking.
+
+**New features & upgrades:**
+
+- **Entity Drift Protection** — The `EntityChangeDetector` runs 11 fast, regex-based validation checks in `< 1ms` to intercept critical entity changes (e.g. Q3 vs Q4, Tesla vs Apple, 100mg vs 200mg) that neural models and cross-encoders often miss.
+- **Domain-Conditioned Thresholds** — Replaces generic risk tiers with domain-specific MLP and Cross-Encoder thresholds (Medical: 0.995/0.97, Finance: 0.990/0.95, Security: 0.997/0.98, Customer Support: 0.90/0.85) to optimize precision/recall trade-offs.
+- **Active Learning Dataset Builder** — Automatically logs MLP vs Cross-Encoder disagreements to the `active_learning_pairs` database table to build hard-negative datasets for continuous retraining.
+- **Safety-Framed Benchmarking** — Rewrote the semantic drift benchmark to compare three systems (Cosine, SM v1, SM v2) on Safety Accuracy (correct blocks), Dangerous False Positive Rate (DFP), and Reuse Accuracy (valid hits).
+- **Comprehensive Tests** — Added 33 unit tests under `tests/test_entity_change_detection.py` validating each regex detector and disabled configurations.
+
+## 1.0.0
+
+First stable release. Published to PyPI as `semanticmemo` (internal import name unchanged: `import semanticmemo`).
+
+This release promotes SemanticMemo from a cosine-threshold semantic cache to a four-stage
+verification pipeline with measured, reproducible false-positive reduction across four
+high-stakes production domains.
+
+**Architecture additions:**
+
+- **Double Verification pipeline** — MLP classifier (stage 3) + Cross-Encoder (stage 4) replace the
+  single cosine threshold. The MLP is fast (~1ms); the Cross-Encoder is high-precision (~3–8ms) and
+  is only invoked when the MLP is uncertain.
+- **Opposite-action veto** — rule-based pre-filter that blocks antonym pairs (approve/deny,
+  buy/sell, increase/decrease, enable/disable, allow/block, grant/revoke, etc.) before any ML
+  stage runs. Catches the canonical hard-negative failure case with zero latency overhead.
+- **Latency-aware MLP bypass** — when the MLP score exceeds `high_precision_skip_threshold`
+  (default 0.995), the Cross-Encoder is skipped entirely. Measured bypass rate: **94.7%** of
+  cache hits; average latency with bypass: **~27ms** vs **~39ms** without.
+- **Domain auto-detection** — `DomainDetector` routes each query to its risk tier using embedding
+  centroids, enabling per-domain threshold policies without explicit domain tagging by the caller.
+- **Risk-aware policy engine** — `RiskPolicy` maps domains to `RiskTier.HIGH` or `RiskTier.LOW`
+  and applies the corresponding MLP/CE thresholds. Ships with sensible defaults:
+  medical/finance/security/legal → HIGH (MLP=0.99, CE=0.95); general/customer-support → LOW (MLP=0.90, CE=0.85).
+- **Explainable `CacheDecision`** — every `CacheResult.decision` records the decision reason,
+  risk tier, per-stage scores, and per-stage latency. Available on both hits and misses.
+
+**Performance and profiling:**
+
+- **Global `_MODEL_CACHE`** in `CrossEncoderService` — the Cross-Encoder is loaded once and
+  shared across all `SemanticMemo` instances in the same process. Eliminates the 1–5 second
+  cold-start penalty on the first inference.
+- **Five new latency profiling fields** on `CacheResult` and `CacheDecision`:
+  `embedding_latency_ms`, `retrieval_latency_ms`, `mlp_latency_ms`, `cross_encoder_latency_ms`,
+  `total_latency_ms`. Enables per-stage bottleneck diagnosis in production.
+
+**Benchmark suite expansion:**
+
+- `benchmarks/run_benchmarks.py` — full 4-method × 4-domain comparison matrix (Cosine Baseline,
+  MLP Classifier, Double Verification, SemanticMemo). Includes per-stage latency breakout table,
+  hard-negative stress test, and Cross-Encoder bypass statistics. Output: `comparison_matrix.json`.
+- `benchmarks/sweep_thresholds.py` — 40 MLP thresholds × 30 CE thresholds = 1,200 configurations
+  per domain, with per-domain FPR constraints (Security < 5%, Finance < 10%). Output:
+  `threshold_report.md` with optimal per-domain config and production recommendation.
+- `benchmarks/data/hard_negatives.jsonl` — 12 curated opposite-action pairs across finance,
+  security, medical, and software domains.
+- All four domain datasets expanded to 20 pairs each (10 positive + 10 hard-negative),
+  replacing the previous 5–10 pair sets.
+- Model warmup in both benchmark scripts eliminates download/load time from measured latency.
+
+**Key measured results:**
+
+| Metric | Cosine Baseline | SemanticMemo |
+| :--- | :---: | :---: |
+| Hard-Negative FPR | 33.3% | **0.0%** |
+| Finance FPR | 20% | **0%** |
+| Security FPR | 20% | **0%** |
+| Medical FPR | 30% | **10%** |
+| Classifier Precision (gold set, equal recall) | 0.527 | **0.829** |
+| CE Bypass Rate | — | **94.7%** |
+| Avg Cache-Hit Latency | — | **~27ms** |
+
+**Documentation:**
+
+- `docs/results.md` — comprehensive 9-section benchmark results document: architecture diagram,
+  full comparison matrix, hard-negative stress test results, latency breakdown, bypass rate
+  analysis, threshold sweep results, cost savings model, and classifier gold-set evaluation.
+- `README.md` rewritten for v1.0.0: problem statement, architecture mermaid diagram, all
+  benchmark tables, full quickstart with production config, project structure, and roadmap.
+
+**Packaging:**
+
+- PyPI package renamed to `semanticmemo`. Internal import name unchanged: `import semanticmemo`.
+- `Development Status` classifier upgraded from Beta to `5 - Production/Stable`.
+- Added `Topic :: Scientific/Engineering :: Artificial Intelligence` classifier.
+- `__version__ = "1.0.0"` exported from `semanticmemo.__init__`.
+
+## 0.3.0
+
+A hardening release: no new product features, but the existing ones become safer to run
+in production. Every change is backward compatible; new configuration is opt-in and off
+by default.
+
+- Add structured logging under the `semanticmemo` logger namespace. The library is silent by
+  default (it attaches only a `NullHandler`); applications opt in by configuring the
+  `semanticmemo` logger.
+- Open the SQLite store in WAL mode with a 5-second busy timeout, and serialize writes
+  with an internal re-entrant lock so one store instance is safe to use from multiple
+  threads of a process. The concurrency guarantees are documented honestly — it is not a
+  distributed cache.
+- Bug fix: enable `PRAGMA foreign_keys`, so the schema's declared `ON DELETE CASCADE`
+  foreign keys now actually fire. Deleting or evicting a cache entry previously left
+  orphan `lookup_records` and `feedback_events` rows behind; it now cleans them up.
+- `SemanticMemo` supports `async with` for guaranteed cleanup; `close()` is unchanged.
+- Add opt-in LLM-call retries: `CacheConfig(retry=RetryConfig(...))` retries transient
+  failures of `llm_function` with bounded exponential backoff. Off by default; only the
+  cache-miss path is retried. Adds the `RetryConfig` model and the `LLMCallError`
+  exception (raised only when retries are enabled and exhausted).
+- CI now tests Python 3.11 through 3.14; the PyPI publish workflow runs the test suite
+  before building and releasing.
+- Add `CONTRIBUTING.md`.
+
+## 0.2.0
+
+- Retrain the bundled classifier as `equivalence-net-v1`: trained on 16,576 labeled pairs
+  across nine domains (adds medical, legal, and finance, plus negation-by-insertion hard
+  negatives). It beats the cosine baseline by +30 precision points at equal recall on the
+  gold set and replaces `classifier-v1` as the shipped checkpoint.
+- Add opt-in implicit-feedback detection: with `CacheConfig(implicit_feedback=...)`,
+  re-issuing the same prompt within a window after a cache hit auto-records a bad-hit
+  event. Off by default; explicit feedback always takes precedence.
+- Add the `ImplicitFeedbackConfig` model and `CacheResult.implicit_bad_hit_recorded`.
+- `get_or_call` now trims surrounding whitespace from the prompt, so the cache key is
+  whitespace-insensitive — prompts differing only by leading or trailing whitespace no
+  longer create duplicate cache entries.
+- Add `benchmarks/false_positive_eval.py` and `benchmarks/data/high_stakes_pairs.jsonl`:
+  a high-stakes medical/legal/finance opposite-action evaluation.
+- Add optional integration examples (`examples/with_orchflow.py`, `with_guardloop.py`,
+  `with_agenteval.py`) composing SemanticMemo with companion libraries; none are
+  dependencies of semanticmemo.
+- Add `docs/feedback.md` covering explicit and implicit feedback and retraining.
+
+## 0.1.0
+
+- Ship `classifier-v1`, a pretrained generic equivalence classifier, inside the package.
+- Add `ClassifierConfig.bundled()` for opt-in, zero-training classifier-gated caching.
+- Add `scripts/generate_training_data.py`: a local-LLM (Ollama) paraphrase and templated
+  hard-negative training-data pipeline, with a committed 10,800-pair dataset.
+- Add a hand-curated 84-pair equivalence gold test set under `data/gold/`.
+- Add `scripts/train_classifier_v1.py` and `benchmarks/classifier_vs_cosine.py`:
+  `classifier-v1` beats the cosine baseline by +32 precision points at equal recall on
+  the gold set.
+- Document that the optional `[ml]` dependencies (PyTorch, FAISS, SentenceTransformers)
+  are required to import semanticmemo.
+
+## 0.0.4
+
+- Add `semanticmemo retrain` for manual feedback-to-checkpoint retraining.
+- Add `semanticmemo.feedback.retrain_from_feedback(...)` with auditable retrain reports.
+- Support optional seed data, validation gates, and checkpoint promotion when gates pass.
+- Document the manual feedback loop from collection through deliberate classifier promotion.
+
+## 0.0.3
+
+- Add durable lookup records for cache hits so feedback can be exported later.
+- Add durable good/bad feedback events tied to cache-hit query IDs.
+- Add `SemanticMemo.export_feedback_pairs(...)` and `semanticmemo export-feedback`.
+- Export feedback-derived JSONL compatible with the classifier training pipeline.
+
+## 0.0.2
+
+- Add optional classifier-gated cache decisions through `SemanticMemo(..., classifier=...)`.
+- Populate `CacheResult.classifier_score` when the classifier evaluates cache candidates.
+- Preserve cosine-threshold behavior when no classifier checkpoint is configured.
+- Document classifier-enabled usage and the current cold-start boundary.
+
+## 0.0.1
+
+Initial SemanticMemo release.
+
+- Async semantic-cache facade with SQLite persistence.
+- Dependency-light hash embeddings for tests and smoke demos.
+- Optional SentenceTransformers and FAISS support through the `ml` extra.
+- Customer-support cosine-baseline benchmark fixture.
+- Pair-classifier model, dataset, training, evaluation, and checkpoint inference utilities.
+- CLI commands for cache stats, classifier training, and classifier evaluation.
+- GitHub Actions CI and PyPI trusted publishing workflow.
+
+

semanticmemo-1.2.0/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to SemanticMemo
+
+Thanks for your interest in SemanticMemo. This guide covers local development, the quality
+gates, and how releases are made.
+
+## Development setup
+
+SemanticMemo uses [uv](https://docs.astral.sh/uv/) for environment and dependency
+management. Python 3.11–3.14 are supported.
+
+```bash
+uv sync --all-extras
+```
+
+The `[ml]` extra (PyTorch, FAISS, SentenceTransformers) is required to import `semanticmemo`
+itself, so `--all-extras` is the normal development sync.
+
+## Quality gates
+
+These four commands are exactly what CI runs. All must pass before a change merges:
+
+```bash
+uv run ruff format --check   # formatting
+uv run ruff check            # lint
+uv run pyright               # type checking
+uv run pytest                # tests
+```
+
+CI runs them on Python 3.11, 3.12, 3.13, and 3.14.
+
+## Concurrency model
+
+The SQLite store opens the database in WAL mode with a 5-second busy timeout. A single
+store instance is safe to use from multiple threads of one process — writes are
+serialized by an internal re-entrant lock, and the connection is created with
+`check_same_thread=False`. SemanticMemo is not a distributed cache: multiple processes
+writing the same database file rely solely on SQLite's file locking, and heavy
+multi-process write contention can still raise `sqlite3.OperationalError`.
+
+## The bundled classifier
+
+The package ships a pretrained equivalence classifier at
+`src/semanticmemo/_models/equivalence-net-v1.pt`, force-included into the wheel by the
+`[tool.hatch.build.targets.wheel.force-include]` table in `pyproject.toml`.
+
+It is reproducible from committed data:
+
+```bash
+# Optional: regenerate the dataset from the prompt corpus (requires a local Ollama model)
+python scripts/generate_training_data.py
+
+# Train and package the classifier from the committed dataset
+uv run python scripts/train_classifier.py
+```
+
+`train_classifier.py` writes the checkpoint plus an auditable model card
+(`equivalence-net-v1.report.json`) next to it. SemanticMemo is precision-first: the acceptance
+gate requires the classifier to beat the cosine baseline by at least 10 precision points
+at equal recall on the held-out gold set. See `docs/ml/` for details.
+
+## Release process
+
+Releases are tag-triggered:
+
+1. Bump `version` in `pyproject.toml`.
+2. Add a new section to `CHANGELOG.md` describing what shipped.
+3. Commit the changes to `main`.
+4. Tag the commit `vX.Y.Z` and push the tag.
+
+Pushing the tag triggers `.github/workflows/publish-pypi.yml`, which runs the full test
+suite before building and publishing to PyPI — a broken tag cannot publish.
+
+

semanticmemo-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rajveer Singh Saggu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.