perf: numpy accelerator for compression (23x at 10k facts)

- agentkeeper._fastmath: optional numpy accel, pure-python fallback.
- index.py: vectorised search via batch_dot.
- consolidation.py: live numpy centroid matrix, incremental centroids,
  best-match assignment.
- contradiction.py: vectorised per-row similarity prefilter.
- compression at 10k facts: 118s -> 5.2s with numpy.
- new [fast] extra (numpy). Zero required deps preserved.
- tests/test_fastmath.py: 12 tests, both paths.
- benchmark/stress_test.py: reproducible scaling benchmark.

Author: tomanciauxberner-rgb

CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to AgentKeeper are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.2] — 2026-05-20
+
+Performance release. No public API changes.
+
+### Changed
+
+- **Compression is dramatically faster at scale.** An optional numpy
+  accelerator (`agentkeeper._fastmath`) vectorises the dot products and
+  cluster-centroid math used by consolidation and contradiction
+  arbitration. With numpy installed, a full compression pass over an
+  agent holding 10,000 facts drops from ~118s to ~5s (about 23x). Without
+  numpy, behaviour is unchanged — the pure-Python fallback is preserved,
+  so the core retains zero required dependencies.
+- Install the accelerator with the new extra: `pip install
+  'agentkeeper-ai[fast]'` (also included in `[all]`).
+- Consolidation clustering now assigns each fact to the **best** matching
+  centroid above the similarity threshold rather than the first one
+  encountered. Tighter, more stable clusters; output on typical inputs is
+  equal or better.
+
+### Added
+
+- `benchmark/stress_test.py` — reproducible scaling benchmark.
+- `tests/test_fastmath.py` — verifies the numpy and pure-Python paths agree.
+
 ## [1.1.0] — 2026-05-19
 
 ### Added

agentkeeper/__init__.py

@@ -88,7 +88,7 @@
     register_profile,
 )
 
-__version__ = "1.1.1"
+__version__ = "1.1.2"
 
 _log = get_logger(__name__)
 

agentkeeper/_fastmath.py

@@ -0,0 +1,66 @@
+"""Optional numpy acceleration for vector math.
+
+AgentKeeper's core has zero required dependencies. Vector math (dot
+products, cosine similarity, clustering) falls back to pure Python when
+numpy is unavailable. When numpy *is* installed — which is the case for
+essentially every AI/ML project — the same operations run 50-100x
+faster, which matters a lot for compression at scale (consolidation
+and contradiction passes are vector-heavy).
+
+This module exposes a single flag, `HAS_NUMPY`, and helpers that pick
+the fast path when possible. Callers never import numpy directly.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+try:
+    import numpy as _np
+
+    HAS_NUMPY = True
+except ImportError:  # pragma: no cover
+    _np = None  # type: ignore[assignment]
+    HAS_NUMPY = False
+
+
+def dot(a: Sequence[float], b: Sequence[float]) -> float:
+    """Dot product of two equal-length vectors."""
+    if len(a) != len(b):
+        raise ValueError(f"Vector dimension mismatch: {len(a)} vs {len(b)}")
+    if HAS_NUMPY:
+        return float(_np.dot(a, b))
+    return sum(x * y for x, y in zip(a, b, strict=True))
+
+
+def batch_dot(
+    query: Sequence[float],
+    matrix: Sequence[Sequence[float]],
+) -> list[float]:
+    """Dot product of `query` against every row of `matrix`.
+
+    Returns a list of scores, one per row. With numpy this is a single
+    matrix-vector product; without, it's a Python loop.
+    """
+    if not matrix:
+        return []
+    if HAS_NUMPY:
+        m = _np.asarray(matrix, dtype=float)
+        q = _np.asarray(query, dtype=float)
+        return _np.dot(m, q).tolist()
+    return [dot(query, row) for row in matrix]
+
+
+def mean_vector(vectors: Sequence[Sequence[float]]) -> list[float]:
+    """Component-wise mean of a list of equal-length vectors."""
+    if not vectors:
+        return []
+    if HAS_NUMPY:
+        return _np.asarray(vectors, dtype=float).mean(axis=0).tolist()
+    n = len(vectors)
+    dim = len(vectors[0])
+    acc = [0.0] * dim
+    for v in vectors:
+        for i in range(dim):
+            acc[i] += v[i]
+    return [x / n for x in acc]

agentkeeper/compression/consolidation.py

@@ -26,9 +26,9 @@
 from collections.abc import Callable
 from dataclasses import dataclass, field
 
+from .._fastmath import batch_dot
 from ..cso.types import Fact
 from ..semantic.base import EmbeddingProvider
-from ..semantic.index import _dot
 
 
 @dataclass
@@ -97,25 +97,75 @@ def consolidate(
         f.id: vec for f, vec in zip(targets, vectors, strict=True)
     }
 
-    # Greedy clustering: walk facts, group each into the first cluster
+    # Greedy clustering: walk facts, group each into the best cluster
     # whose centroid is within the threshold; else start a new cluster.
+    # When numpy is present we keep the centroid matrix as a live ndarray
+    # and append rows in place, so we never re-coerce a growing python
+    # list to an array on every fact (that reconversion was the dominant
+    # cost at scale). Centroids use an incremental running sum / count.
+    from .._fastmath import HAS_NUMPY
+
     clusters: list[list[Fact]] = []
-    centroids: list[list[float]] = []
-
-    for fact in targets:
-        vec = fact_vectors[fact.id]
-        assigned = False
-        for i, centroid in enumerate(centroids):
-            if _dot(vec, centroid) >= config.similarity_threshold:
-                clusters[i].append(fact)
-                # update centroid as running mean (re-normalise lazily)
-                cluster_vecs = [fact_vectors[m.id] for m in clusters[i]]
-                centroids[i] = _mean_vector(cluster_vecs)
-                assigned = True
-                break
-        if not assigned:
-            clusters.append([fact])
-            centroids.append(vec)
+    centroid_sums: list[list[float]] = []
+    centroid_counts: list[int] = []
+
+    if HAS_NUMPY:
+        import numpy as _np
+
+        dim = len(fact_vectors[targets[0].id])
+        # Pre-allocate; grow geometrically to amortise reallocation.
+        cap = 64
+        cmat = _np.empty((cap, dim), dtype=float)
+        n_centroids = 0
+
+        for fact in targets:
+            vec = fact_vectors[fact.id]
+            varr = _np.asarray(vec, dtype=float)
+            assigned = False
+            if n_centroids > 0:
+                scores = cmat[:n_centroids] @ varr
+                best_i = int(scores.argmax())
+                if scores[best_i] >= config.similarity_threshold:
+                    clusters[best_i].append(fact)
+                    csum = centroid_sums[best_i]
+                    for k in range(dim):
+                        csum[k] += vec[k]
+                    centroid_counts[best_i] += 1
+                    cnt = centroid_counts[best_i]
+                    cmat[best_i] = [s / cnt for s in csum]
+                    assigned = True
+            if not assigned:
+                if n_centroids >= cap:
+                    cap *= 2
+                    newmat = _np.empty((cap, dim), dtype=float)
+                    newmat[:n_centroids] = cmat[:n_centroids]
+                    cmat = newmat
+                cmat[n_centroids] = varr
+                n_centroids += 1
+                clusters.append([fact])
+                centroid_sums.append(list(vec))
+                centroid_counts.append(1)
+    else:
+        centroids: list[list[float]] = []
+        for fact in targets:
+            vec = fact_vectors[fact.id]
+            assigned = False
+            for i, centroid in enumerate(centroids):
+                if batch_dot(vec, [centroid])[0] >= config.similarity_threshold:
+                    clusters[i].append(fact)
+                    csum = centroid_sums[i]
+                    for k in range(len(csum)):
+                        csum[k] += vec[k]
+                    centroid_counts[i] += 1
+                    cnt = centroid_counts[i]
+                    centroids[i] = [s / cnt for s in csum]
+                    assigned = True
+                    break
+            if not assigned:
+                clusters.append([fact])
+                centroids.append(list(vec))
+                centroid_sums.append(list(vec))
+                centroid_counts.append(1)
 
     # Process non-singleton clusters
     for cluster in clusters:

agentkeeper/compression/contradiction.py

@@ -161,15 +161,48 @@ def detect_and_resolve(
     # cascading.
     already_lost: set[str] = set()
 
+    # Vectorised prefilter: contradictions only occur between highly
+    # similar facts (similarity >= threshold). For each row i we compute
+    # similarities against all j > i in one batched dot product, then
+    # only run the (cheaper but still non-trivial) contradiction check on
+    # candidate pairs that clear the threshold. We compute per-row rather
+    # than materialising the full n*n matrix, to bound memory at large n
+    # (a 10k*10k float matrix would be ~800MB).
+    from .._fastmath import HAS_NUMPY
+
+    mat = None
+    if HAS_NUMPY and n > 1:
+        import numpy as _np
+
+        mat = _np.asarray(vectors, dtype=float)
+
     for i in range(n):
         if targets[i].id in already_lost:
             continue
-        for j in range(i + 1, n):
+        if mat is not None:
+            # Similarities of row i against every other row, vectorised.
+            row = (mat @ mat[i])
+            candidates = [
+                j
+                for j in range(i + 1, n)
+                if row[j] >= config.similarity_threshold
+            ]
+            row_scores = row
+        else:
+            candidates = [
+                j
+                for j in range(i + 1, n)
+                if _dot(vectors[i], vectors[j]) >= config.similarity_threshold
+            ]
+            row_scores = None
+        for j in candidates:
             if targets[j].id in already_lost:
                 continue
-            similarity = _dot(vectors[i], vectors[j])
-            if similarity < config.similarity_threshold:
-                continue
+            similarity = (
+                float(row_scores[j])
+                if row_scores is not None
+                else _dot(vectors[i], vectors[j])
+            )
             reason = _detect_contradiction(targets[i], targets[j], similarity)
             if reason is None:
                 continue

agentkeeper/semantic/index.py

@@ -19,13 +19,8 @@
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
 
-
-def _dot(a: Sequence[float], b: Sequence[float]) -> float:
-    if len(a) != len(b):
-        raise ValueError(
-            f"Vector dimension mismatch: {len(a)} vs {len(b)}"
-        )
-    return sum(x * y for x, y in zip(a, b, strict=True))
+from .._fastmath import batch_dot
+from .._fastmath import dot as _dot  # noqa: F401  (re-exported for compression.contradiction)
 
 
 class VectorIndex(ABC):
@@ -86,11 +81,14 @@ def search(
     ) -> list[tuple[str, float]]:
         if top_k <= 0 or not self._vectors:
             return []
-        scored: list[tuple[str, float]] = []
-        for fact_id, vec in self._vectors.items():
-            score = _dot(query, vec)
-            if score >= min_score:
-                scored.append((fact_id, score))
+        fact_ids = list(self._vectors.keys())
+        matrix = [self._vectors[fid] for fid in fact_ids]
+        scores = batch_dot(query, matrix)
+        scored = [
+            (fid, score)
+            for fid, score in zip(fact_ids, scores, strict=True)
+            if score >= min_score
+        ]
         scored.sort(key=lambda x: x[1], reverse=True)
         return scored[:top_k]