eigenmind 0.1.0__tar.gz

eigenmind-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Merlin Intelligence
+
+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.

eigenmind-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: eigenmind
+Version: 0.1.0
+Summary: Eigenvalue-based graph computations for semantic chunk retrieval (similarity graph, spectral analysis, Lovász theta diversity).
+Author-email: Marion Schaeffer <marion.schaeffer@merlin-intelligence.eu>
+License: MIT
+Project-URL: Homepage, https://github.com/merlin-intelligence/eigenmind
+Project-URL: Repository, https://github.com/merlin-intelligence/eigenmind
+Project-URL: Issues, https://github.com/merlin-intelligence/eigenmind/issues
+Keywords: graph,eigenvalue,spectral-clustering,embeddings,retrieval,diversity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: viz
+Requires-Dist: matplotlib; extra == "viz"
+Dynamic: license-file
+
+# eigenmind
+Eigenmind is a decision-intelligence engine that turns tacit expert knowledge into reusable decision frameworks, ideal for data-scarce settings. Its core uses eigenvalue-based optimisation on semantic graphs.
+
+## Install
+
+```bash
+pip install git+https://github.com/merlin-intelligence/eigenmind.git
+```
+
+## Usage
+
+```python
+from eigenmind import SimilarityGraph
+
+# retrieved_points: objects with .id, .vector, .payload (e.g. Qdrant points)
+graph = SimilarityGraph(retrieved_points)
+tags = graph.selection_tags(top_k=10)  # {chunk_id: ["Singular", "Hinge", "Theta"]}
+```
+
+### Expected input data
+
+`retrieved_points` is a plain list of objects — any class works (duck-typing,
+modeled after Qdrant's point objects), each exposing:
+
+| Attribute | Type | Constraint |
+|---|---|---|
+| `.id` | hashable (`int`, `str`, `UUID`, ...) | unique across the list — used as a dict key |
+| `.vector` | sequence of floats (`list` or `np.ndarray`) | **same length for every point**, and **unit-normalized (L2 norm ≈ 1)** |
+| `.payload` | `dict` | only read by `eigenvalue_analysis`, via `.get("text")`, `.get("chunk_number")`, `.get("filename")` |
+
+The library computes cosine similarity as a plain dot product between
+vectors (`embedding_matrix @ embedding_matrix.T`) — it does **not** normalize
+your vectors for you. Passing unnormalized vectors raises a `ValueError`
+(from `build_similarity_matrix`, used internally by `SimilarityGraph` and
+`find_singular_chunks`); normalize each vector yourself first, e.g.
+`v / np.linalg.norm(v)`.
+
+A `types.SimpleNamespace(id=..., vector=..., payload={...})` is enough — no
+dependency on Qdrant is required, as shown in the test suite. Because the
+interface is duck-typed on these three attributes, results from any
+vector store (Pinecone, Weaviate, Milvus, pgvector, Chroma, ...) work as-is,
+either directly or after a thin adapter mapping their result objects to
+`.id` / `.vector` / `.payload`.
+
+`SimilarityGraph` memoizes the similarity matrix and exposes four ranking
+strategies over a set of embedded chunks:
+
+- **Singular chunks** — points at the +/- poles of the normalized Laplacian's
+  first eigenvectors (`singular.py`).
+- **Hinge ranking** — "relevant but not obvious" chunks via an ℓ∞-connectivity
+  optimizer (`connectivity.py`).
+- **Theta diversity** — a diverse subset picked via a Lovász θ approximation on
+  the conflict graph (`theta.py`).
+- **Eigenvalue analysis** — spectrum plot + most expressive chunks per
+  eigenvector, for exploratory/debugging use. Requires the `viz` extra
+  (`pip install eigenmind[viz]`).
+
+
+## Configuration
+
+Every tunable is a plain keyword argument with a default from
+[`defaults.py`](src/eigenmind/defaults.py) — override it per call/instance,
+there is no global state to mutate.
+
+| Constant | Default | Meaning | Override via |
+|---|---|---|---|
+| `SIMILARITY_THRESHOLD` | `0.65` | Minimum cosine similarity kept as an edge weight; pairs below it are zeroed out of `W`. | `SimilarityGraph(points, threshold=...)`, `build_similarity_matrix(..., threshold=...)` |
+| `THETA_CONFLICT_THRESHOLD` | `= SIMILARITY_THRESHOLD` | Similarity level above which two chunks are considered "conflicting" (same info) for the θ diversity graph. | `SimilarityGraph.conflict_mask(threshold=...)`, `build_conflict_mask(..., threshold=...)` |
+| `THETA_RANK` | `24` | Rank of the low-rank factor `Y` (`X ≈ Y Yᵀ`) used by the diversity picker — caps how many effective directions the θ approximation keeps. | `SimilarityGraph.theta_factor(rank=...)`, `theta_subgradient_approximation(..., rank=...)` |
+| `THETA_MAX_ITERS` | `400` | Number of subgradient-descent iterations for the Lovász θ approximation. | `SimilarityGraph.theta_factor(max_iters=...)`, `theta_subgradient_approximation(..., max_iters=...)` |
+| `THETA_STEP0` | `0.25` | Initial subgradient step size, decayed as `step0 / sqrt(k)` over iterations. | `SimilarityGraph.theta_factor(step0=...)`, `theta_subgradient_approximation(..., step0=...)` |
+| `THETA_DIAG_SHIFT` | `1e-2` | Diagonal regularization added when the dual matrix isn't Cholesky-decomposable (numerical stabilizer). | `SimilarityGraph.theta_factor(diag_shift=...)`, `theta_subgradient_approximation(..., diag_shift=...)` |
+
+These defaults are the values the algorithms were originally tuned against;
+adjust them if your embeddings' similarity distribution differs
+significantly (e.g. a different embedding model or normalization scheme).
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

eigenmind-0.1.0/README.md

@@ -0,0 +1,83 @@
+# eigenmind
+Eigenmind is a decision-intelligence engine that turns tacit expert knowledge into reusable decision frameworks, ideal for data-scarce settings. Its core uses eigenvalue-based optimisation on semantic graphs.
+
+## Install
+
+```bash
+pip install git+https://github.com/merlin-intelligence/eigenmind.git
+```
+
+## Usage
+
+```python
+from eigenmind import SimilarityGraph
+
+# retrieved_points: objects with .id, .vector, .payload (e.g. Qdrant points)
+graph = SimilarityGraph(retrieved_points)
+tags = graph.selection_tags(top_k=10)  # {chunk_id: ["Singular", "Hinge", "Theta"]}
+```
+
+### Expected input data
+
+`retrieved_points` is a plain list of objects — any class works (duck-typing,
+modeled after Qdrant's point objects), each exposing:
+
+| Attribute | Type | Constraint |
+|---|---|---|
+| `.id` | hashable (`int`, `str`, `UUID`, ...) | unique across the list — used as a dict key |
+| `.vector` | sequence of floats (`list` or `np.ndarray`) | **same length for every point**, and **unit-normalized (L2 norm ≈ 1)** |
+| `.payload` | `dict` | only read by `eigenvalue_analysis`, via `.get("text")`, `.get("chunk_number")`, `.get("filename")` |
+
+The library computes cosine similarity as a plain dot product between
+vectors (`embedding_matrix @ embedding_matrix.T`) — it does **not** normalize
+your vectors for you. Passing unnormalized vectors raises a `ValueError`
+(from `build_similarity_matrix`, used internally by `SimilarityGraph` and
+`find_singular_chunks`); normalize each vector yourself first, e.g.
+`v / np.linalg.norm(v)`.
+
+A `types.SimpleNamespace(id=..., vector=..., payload={...})` is enough — no
+dependency on Qdrant is required, as shown in the test suite. Because the
+interface is duck-typed on these three attributes, results from any
+vector store (Pinecone, Weaviate, Milvus, pgvector, Chroma, ...) work as-is,
+either directly or after a thin adapter mapping their result objects to
+`.id` / `.vector` / `.payload`.
+
+`SimilarityGraph` memoizes the similarity matrix and exposes four ranking
+strategies over a set of embedded chunks:
+
+- **Singular chunks** — points at the +/- poles of the normalized Laplacian's
+  first eigenvectors (`singular.py`).
+- **Hinge ranking** — "relevant but not obvious" chunks via an ℓ∞-connectivity
+  optimizer (`connectivity.py`).
+- **Theta diversity** — a diverse subset picked via a Lovász θ approximation on
+  the conflict graph (`theta.py`).
+- **Eigenvalue analysis** — spectrum plot + most expressive chunks per
+  eigenvector, for exploratory/debugging use. Requires the `viz` extra
+  (`pip install eigenmind[viz]`).
+
+
+## Configuration
+
+Every tunable is a plain keyword argument with a default from
+[`defaults.py`](src/eigenmind/defaults.py) — override it per call/instance,
+there is no global state to mutate.
+
+| Constant | Default | Meaning | Override via |
+|---|---|---|---|
+| `SIMILARITY_THRESHOLD` | `0.65` | Minimum cosine similarity kept as an edge weight; pairs below it are zeroed out of `W`. | `SimilarityGraph(points, threshold=...)`, `build_similarity_matrix(..., threshold=...)` |
+| `THETA_CONFLICT_THRESHOLD` | `= SIMILARITY_THRESHOLD` | Similarity level above which two chunks are considered "conflicting" (same info) for the θ diversity graph. | `SimilarityGraph.conflict_mask(threshold=...)`, `build_conflict_mask(..., threshold=...)` |
+| `THETA_RANK` | `24` | Rank of the low-rank factor `Y` (`X ≈ Y Yᵀ`) used by the diversity picker — caps how many effective directions the θ approximation keeps. | `SimilarityGraph.theta_factor(rank=...)`, `theta_subgradient_approximation(..., rank=...)` |
+| `THETA_MAX_ITERS` | `400` | Number of subgradient-descent iterations for the Lovász θ approximation. | `SimilarityGraph.theta_factor(max_iters=...)`, `theta_subgradient_approximation(..., max_iters=...)` |
+| `THETA_STEP0` | `0.25` | Initial subgradient step size, decayed as `step0 / sqrt(k)` over iterations. | `SimilarityGraph.theta_factor(step0=...)`, `theta_subgradient_approximation(..., step0=...)` |
+| `THETA_DIAG_SHIFT` | `1e-2` | Diagonal regularization added when the dual matrix isn't Cholesky-decomposable (numerical stabilizer). | `SimilarityGraph.theta_factor(diag_shift=...)`, `theta_subgradient_approximation(..., diag_shift=...)` |
+
+These defaults are the values the algorithms were originally tuned against;
+adjust them if your embeddings' similarity distribution differs
+significantly (e.g. a different embedding model or normalization scheme).
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

eigenmind-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "eigenmind"
+version = "0.1.0"
+description = "Eigenvalue-based graph computations for semantic chunk retrieval (similarity graph, spectral analysis, Lovász theta diversity)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Marion Schaeffer", email = "marion.schaeffer@merlin-intelligence.eu" },
+]
+keywords = ["graph", "eigenvalue", "spectral-clustering", "embeddings", "retrieval", "diversity"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+dependencies = [
+    "numpy",
+    "scipy",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff"]
+viz = ["matplotlib"]
+
+[project.urls]
+Homepage = "https://github.com/merlin-intelligence/eigenmind"
+Repository = "https://github.com/merlin-intelligence/eigenmind"
+Issues = "https://github.com/merlin-intelligence/eigenmind/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+eigenmind = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+extend-exclude = [".venv", "venv", "build", "dist"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+    "SIM", # flake8-simplify
+]
+ignore = [
+    "E501", # line too long (handled by formatter)
+    "B008", # do not perform function calls in argument defaults
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B"]
+"__init__.py" = ["F401"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"

eigenmind-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

eigenmind-0.1.0/src/eigenmind/__init__.py

@@ -0,0 +1,37 @@
+"""eigenmind — eigenvalue-based graph computations for semantic chunk retrieval.
+
+Public API re-exported here for convenience::
+
+    from eigenmind import SimilarityGraph
+"""
+from __future__ import annotations
+
+from eigenmind.connectivity import (
+    compute_linf_connectivity_optimizer,
+    rank_relevant_but_not_obvious_chunks,
+)
+from eigenmind.similarity_graph import SimilarityGraph
+from eigenmind.singular import (
+    analyze_laplacian_eigenvectors,
+    build_similarity_matrix,
+    find_singular_chunks,
+    normalized_laplacian,
+)
+from eigenmind.theta import (
+    build_conflict_mask,
+    theta_diversity_picker,
+    theta_subgradient_approximation,
+)
+
+__all__ = [
+    "SimilarityGraph",
+    "analyze_laplacian_eigenvectors",
+    "build_conflict_mask",
+    "build_similarity_matrix",
+    "compute_linf_connectivity_optimizer",
+    "find_singular_chunks",
+    "normalized_laplacian",
+    "rank_relevant_but_not_obvious_chunks",
+    "theta_diversity_picker",
+    "theta_subgradient_approximation",
+]

eigenmind-0.1.0/src/eigenmind/connectivity.py

@@ -0,0 +1,118 @@
+"""ℓ∞-connectivity optimizer + hinge ranking ("relevant but not obvious" chunks)."""
+from __future__ import annotations
+
+import heapq
+
+import numpy as np
+
+
+def _build_weighted_lengths(W: np.ndarray, eps: float = 1e-12) -> np.ndarray:
+    """Convert similarity weights W_ij in [0,1] into positive edge lengths via -log."""
+    L = np.full_like(W, np.inf, dtype=float)
+    mask = W > 0
+    L[mask] = -np.log(np.clip(W[mask], eps, 1.0))
+    np.fill_diagonal(L, 0.0)
+    return L
+
+
+def _dijkstra_all_sources(lengths: np.ndarray) -> np.ndarray:
+    """All-pairs shortest paths via Dijkstra from each node (dense, OK for n<=~500)."""
+    n = lengths.shape[0]
+    dist = np.full((n, n), np.inf, dtype=float)
+
+    for src in range(n):
+        d = dist[src]
+        d[src] = 0.0
+        pq = [(0.0, src)]
+        visited = np.zeros(n, dtype=bool)
+
+        while pq:
+            du, u = heapq.heappop(pq)
+            if visited[u]:
+                continue
+            visited[u] = True
+
+            for v in range(n):
+                w = lengths[u, v]
+                if w == np.inf or v == u:
+                    continue
+                nd = du + w
+                if nd < d[v]:
+                    d[v] = nd
+                    heapq.heappush(pq, (nd, v))
+
+    return dist
+
+
+def compute_linf_connectivity_optimizer(W: np.ndarray) -> np.ndarray:
+    """Practical ℓ∞-connectivity optimizer x* in chunk space."""
+    n = W.shape[0]
+    degrees = np.sum(W, axis=1)
+    if np.all(degrees == 0):
+        return np.zeros(n, dtype=float)
+
+    lengths = _build_weighted_lengths(W)
+    dist = _dijkstra_all_sources(lengths)
+
+    finite = np.isfinite(dist)
+    if not np.all(finite):
+        max_finite = np.max(dist[finite]) if np.any(finite) else 1.0
+        dist = np.where(finite, dist, 10.0 * max_finite)
+
+    transmission = np.sum(dist, axis=1)
+    v_star = int(np.argmax(transmission))
+
+    x_raw = dist[v_star, :].copy()
+
+    deg_sum = float(np.sum(degrees))
+    if deg_sum > 0:
+        weighted_mean = float(np.sum(degrees * x_raw)) / deg_sum
+        x_centered = x_raw - weighted_mean
+    else:
+        x_centered = x_raw - np.mean(x_raw)
+
+    denom = float(np.max(np.abs(x_centered)))
+    if denom < 1e-12:
+        return np.zeros(n, dtype=float)
+
+    return x_centered / denom
+
+
+def rank_relevant_but_not_obvious_chunks(
+    W: np.ndarray,
+    x_star: np.ndarray,
+    pole_quantile: float = 0.90,
+):
+    """Chunk-only retrieval of relevant-but-not-obvious items.
+
+    Returns (ranking, P_plus, P_minus, q_hi, q_lo). Each ranking entry is
+    ``(idx, hinge_score, bridge, S_plus, S_minus, x_i)``.
+    """
+    x = x_star
+    q_hi = float(np.quantile(x, pole_quantile))
+    q_lo = float(np.quantile(x, 1.0 - pole_quantile))
+
+    Pp = np.where(x >= q_hi)[0]
+    Pm = np.where(x <= q_lo)[0]
+
+    if len(Pp) == 0 or len(Pm) == 0:
+        q_hi = float(np.quantile(x, 0.80))
+        q_lo = float(np.quantile(x, 0.20))
+        Pp = np.where(x >= q_hi)[0]
+        Pm = np.where(x <= q_lo)[0]
+
+    S_plus = np.sum(W[:, Pp], axis=1) if len(Pp) > 0 else np.zeros(W.shape[0])
+    S_minus = np.sum(W[:, Pm], axis=1) if len(Pm) > 0 else np.zeros(W.shape[0])
+
+    bridge = np.minimum(S_plus, S_minus)
+    hinge = bridge * (1.0 - np.abs(x))
+
+    ranking = sorted(
+        [
+            (i, float(hinge[i]), float(bridge[i]), float(S_plus[i]), float(S_minus[i]), float(x[i]))
+            for i in range(W.shape[0])
+        ],
+        key=lambda t: t[1],
+        reverse=True,
+    )
+    return ranking, Pp, Pm, q_hi, q_lo

eigenmind-0.1.0/src/eigenmind/defaults.py

@@ -0,0 +1,14 @@
+"""Default parameter values for the graph algorithms.
+
+Every public function accepts these as overridable keyword arguments; the
+values below are the ones the algorithms were originally tuned against.
+"""
+from __future__ import annotations
+
+SIMILARITY_THRESHOLD = 0.65
+
+THETA_CONFLICT_THRESHOLD = SIMILARITY_THRESHOLD
+THETA_RANK = 24
+THETA_MAX_ITERS = 400
+THETA_STEP0 = 0.25
+THETA_DIAG_SHIFT = 1e-2

eigenmind-0.1.0/src/eigenmind/similarity_graph.py

@@ -0,0 +1,142 @@
+"""``SimilarityGraph`` — high-level API around the graph math primitives.
+
+Holds a similarity matrix W and exposes the four ranking strategies (singular,
+hinge, theta, eigenvalue analysis) without recomputing W or the conflict mask
+every time. The lower-level pure functions in
+:mod:`eigenmind.singular`, :mod:`eigenmind.connectivity` and
+:mod:`eigenmind.theta` remain available and are still directly tested.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from eigenmind.connectivity import (
+    compute_linf_connectivity_optimizer,
+    rank_relevant_but_not_obvious_chunks,
+)
+from eigenmind.defaults import (
+    SIMILARITY_THRESHOLD,
+    THETA_CONFLICT_THRESHOLD,
+    THETA_DIAG_SHIFT,
+    THETA_MAX_ITERS,
+    THETA_RANK,
+    THETA_STEP0,
+)
+from eigenmind.singular import (
+    analyze_laplacian_eigenvectors,
+    build_similarity_matrix,
+    find_singular_chunks,
+    normalized_laplacian,
+)
+from eigenmind.theta import (
+    build_conflict_mask,
+    theta_diversity_picker,
+    theta_subgradient_approximation,
+)
+
+
+class SimilarityGraph:
+    """A weighted graph over chunks, built from their embedding matrix.
+
+    Memoizes the similarity matrix, the ℓ∞ optimizer, the conflict mask and the
+    θ low-rank factor so clients that ask for several rankings only pay the cost
+    once.
+    """
+
+    def __init__(
+        self,
+        retrieved_points: list,
+        threshold: float = SIMILARITY_THRESHOLD,
+    ):
+        self.points = retrieved_points
+        self.threshold = threshold
+        self.id_to_point = {p.id: p for p in retrieved_points}
+        self.ordered_ids = [p.id for p in retrieved_points]
+        self.embedding_matrix = (
+            np.array([p.vector for p in retrieved_points])
+            if retrieved_points
+            else np.empty((0, 0))
+        )
+        self.W = build_similarity_matrix(self.embedding_matrix, threshold) if len(retrieved_points) else np.empty((0, 0))
+        self._x_star: np.ndarray | None = None
+        self._conflict_mask: np.ndarray | None = None
+        self._theta_factor: np.ndarray | None = None
+
+    # ─── basic linear algebra ──────────────────────────────────────
+
+    @property
+    def n(self) -> int:
+        return self.W.shape[0]
+
+    def laplacian(self) -> np.ndarray:
+        return normalized_laplacian(self.W)
+
+    # ─── strategy 1: singular chunks (eigenvector poles) ───────────
+
+    def singular_chunks(self) -> list:
+        """Points lying at the +/- poles of the first k Laplacian eigenvectors."""
+        return find_singular_chunks(self.points, W=self.W)
+
+    def eigenvalue_analysis(self, output_filename_base: str):
+        """Persist the eigenvalue plot and return the per-chunk EV pole tags."""
+        return analyze_laplacian_eigenvectors(self.W, self.id_to_point, self.ordered_ids, output_filename_base)
+
+    # ─── strategy 2: ℓ∞ connectivity + hinge ranking ───────────────
+
+    def linf_optimizer(self) -> np.ndarray:
+        """Memoized ``x*`` — the ℓ∞-connectivity optimizer."""
+        if self._x_star is None:
+            self._x_star = compute_linf_connectivity_optimizer(self.W)
+        return self._x_star
+
+    def hinge_ranking(self, pole_quantile: float = 0.90):
+        """Ranking of relevant-but-not-obvious chunks. See :func:`rank_relevant_but_not_obvious_chunks`."""
+        return rank_relevant_but_not_obvious_chunks(self.W, self.linf_optimizer(), pole_quantile)
+
+    # ─── strategy 3: Lovász θ + diversity ──────────────────────────
+
+    def conflict_mask(self, threshold: float = THETA_CONFLICT_THRESHOLD) -> np.ndarray:
+        if self._conflict_mask is None:
+            self._conflict_mask = build_conflict_mask(self.W, threshold)
+        return self._conflict_mask
+
+    def theta_factor(
+        self,
+        max_iters: int = THETA_MAX_ITERS,
+        step0: float = THETA_STEP0,
+        diag_shift: float = THETA_DIAG_SHIFT,
+        rank: int = THETA_RANK,
+    ) -> np.ndarray:
+        """Memoized low-rank factor Y from the θ approximation."""
+        if self._theta_factor is None:
+            _, _, Y, _, _, _ = theta_subgradient_approximation(
+                self.conflict_mask(),
+                max_iters=max_iters, step0=step0, diag_shift=diag_shift, rank=rank,
+            )
+            self._theta_factor = Y
+        return self._theta_factor
+
+    def theta_diversity(self, k: int = 10, seed: str = "leverage") -> list[int]:
+        """Indices of ``k`` diverse chunks in the conflict graph."""
+        selected, _ = theta_diversity_picker(self.theta_factor(), k=k, seed=seed)
+        return selected
+
+    # ─── consensus across strategies ───────────────────────────────
+
+    def selection_tags(self, top_k: int = 10) -> dict:
+        """Return ``{chunk_id: [tags...]}`` aggregating singular/hinge/theta selections."""
+        tags: dict = {}
+        if self.n == 0:
+            return tags
+
+        for p in self.singular_chunks():
+            tags.setdefault(p.id, []).append("Singular")
+
+        if self.n > 2:
+            ranking, _, _, _, _ = self.hinge_ranking()
+            for r in ranking[:top_k]:
+                tags.setdefault(self.ordered_ids[r[0]], []).append("Hinge")
+            for idx in self.theta_diversity(k=top_k):
+                tags.setdefault(self.ordered_ids[idx], []).append("Theta")
+
+        return tags

eigenmind-0.1.0/src/eigenmind/singular.py

@@ -0,0 +1,165 @@
+"""Singular chunks via eigenvector poles of the symmetric normalized Laplacian."""
+from __future__ import annotations
+
+import textwrap
+
+import numpy as np
+from scipy.linalg import eigh
+
+from eigenmind.defaults import SIMILARITY_THRESHOLD
+
+
+def build_similarity_matrix(embedding_matrix: np.ndarray, threshold: float = SIMILARITY_THRESHOLD) -> np.ndarray:
+    """Cosine-similarity matrix with sub-threshold values zeroed and zero diagonal.
+
+    ``embedding_matrix`` rows must already be unit-normalized (L2 norm ≈ 1):
+    the similarity is a plain row-wise dot product, not a normalized cosine,
+    so unnormalized vectors would silently produce a meaningless matrix.
+    """
+    if embedding_matrix.size:
+        norms = np.linalg.norm(embedding_matrix, axis=1)
+        bad = np.where(np.abs(norms - 1.0) > 1e-3)[0]
+        if len(bad):
+            raise ValueError(
+                "embedding_matrix rows must be unit-normalized (L2 norm ≈ 1); "
+                f"{len(bad)} row(s) are not, e.g. row {int(bad[0])} has norm "
+                f"{norms[bad[0]]:.4f}. Normalize each vector (v / np.linalg.norm(v)) "
+                "before building a SimilarityGraph."
+            )
+    W = embedding_matrix @ embedding_matrix.T
+    W[W < threshold] = 0
+    np.fill_diagonal(W, 0)
+    return W
+
+
+def normalized_laplacian(W: np.ndarray) -> np.ndarray:
+    degrees = np.sum(W, axis=1)
+    d_inv_sqrt = np.zeros_like(degrees)
+    nz = degrees > 0
+    d_inv_sqrt[nz] = 1.0 / np.sqrt(degrees[nz])
+    D_inv_sqrt = np.diag(d_inv_sqrt)
+    return np.identity(W.shape[0]) - D_inv_sqrt @ W @ D_inv_sqrt
+
+
+def find_singular_chunks(
+    retrieved_points: list,
+    W: np.ndarray | None = None,
+    threshold: float = SIMILARITY_THRESHOLD,
+) -> list:
+    """Return points lying at the +/- poles of the first k Laplacian eigenvectors.
+
+    Pass ``W`` (e.g. ``SimilarityGraph.W``) to reuse an already-built similarity
+    matrix instead of recomputing one from ``threshold``.
+    """
+    if len(retrieved_points) < 2:
+        return []
+
+    id_to_point = {p.id: p for p in retrieved_points}
+    ordered_ids = [p.id for p in retrieved_points]
+
+    if W is None:
+        embedding_matrix = np.array([p.vector for p in retrieved_points])
+        W = build_similarity_matrix(embedding_matrix, threshold)
+
+    L_sym = normalized_laplacian(W)
+    eigenvalues, eigenvectors = eigh(L_sym)
+
+    zero_threshold = 1e-3
+    k = int(np.sum(eigenvalues < zero_threshold))
+
+    out: list = []
+    seen: set = set()
+    for i in range(1, min(k + 1, len(eigenvalues))):
+        ev = eigenvectors[:, i]
+        for idx in (int(np.argmax(ev)), int(np.argmin(ev))):
+            pid = ordered_ids[idx]
+            if pid not in seen:
+                seen.add(pid)
+                out.append(id_to_point[pid])
+    return out
+
+
+def analyze_laplacian_eigenvectors(
+    similarity_matrix: np.ndarray,
+    id_to_point: dict,
+    ordered_ids: list,
+    output_filename_base: str,
+):
+    """Compute the Laplacian spectrum and identify the most expressive chunks per eigenvector.
+
+    Returns (plot_path, summary_text, singular_info) where singular_info maps
+    chunk-index → list of tags like "EV3(+)".
+
+    Requires the ``matplotlib`` extra (``pip install eigenmind[viz]``).
+    """
+    try:
+        import matplotlib.pyplot as plt
+    except ImportError as e:
+        raise ImportError(
+            "analyze_laplacian_eigenvectors requires matplotlib. "
+            "Install it with: pip install eigenmind[viz]"
+        ) from e
+
+    summary: list[str] = []
+    singular_info: dict[int, list[str]] = {}
+
+    L_sym = normalized_laplacian(similarity_matrix)
+    eigenvalues, eigenvectors = eigh(L_sym)
+
+    zero_threshold = 1e-3
+    zero_multiplicity = int(np.sum(eigenvalues < zero_threshold))
+    summary.append(
+        f"Found {zero_multiplicity} connected components (eigenvalues < {zero_threshold})."
+    )
+
+    n_to_plot = min(20, len(eigenvalues))
+    plt.figure(figsize=(10, 6))
+    plt.plot(range(1, n_to_plot + 1), eigenvalues[:n_to_plot], "o-")
+    plt.title("Eigenvalues of the Graph Laplacian (Spectrum)")
+    plt.xlabel(f"Eigenvalue Index (Sorted) - First {zero_multiplicity} are near-zero")
+    plt.ylabel("Eigenvalue")
+    plt.xticks(range(1, n_to_plot + 1))
+    plt.grid(True)
+    plot_filename = f"{output_filename_base}_eigenvalues.png"
+    try:
+        plt.savefig(plot_filename)
+        summary.append(f"Eigenvalue plot saved to '{plot_filename}'")
+    except Exception as e:  # noqa: BLE001
+        summary.append(f"Could not save eigenvalue plot. Error: {e}")
+    plt.close()
+
+    summary.append("\nMost expressive chunks along the primary semantic axes (eigenvectors):")
+    for i in range(1, min(zero_multiplicity + 5, len(eigenvalues))):
+        ev = eigenvectors[:, i]
+        pos_idx = np.argsort(ev)[-3:]
+        neg_idx = np.argsort(ev)[:3]
+
+        for idx in pos_idx:
+            singular_info.setdefault(int(idx), []).append(f"EV{i + 1}(+)")
+        for idx in neg_idx:
+            singular_info.setdefault(int(idx), []).append(f"EV{i + 1}(-)")
+
+        summary.append(f"\n--- EIGENVECTOR {i + 1} (Eigenvalue: {eigenvalues[i]:.4f}) ---")
+        summary.append("  (+) Positive Pole Chunks:")
+        for idx in reversed(pos_idx):
+            point = id_to_point[ordered_ids[idx]]
+            text = " ".join(point.payload.get("text", "N/A").split())
+            wrapped = textwrap.fill(text, width=120, initial_indent=" " * 6, subsequent_indent=" " * 6)
+            summary.append(
+                f"    - (Score: {ev[idx]:.3f}) "
+                f"[{point.payload.get('chunk_number', 'N/A')} | {point.payload.get('filename', 'N/A')}]"
+            )
+            summary.append(f'      "{wrapped.strip()}"')
+
+        summary.append("\n  (-) Negative Pole Chunks:")
+        for idx in neg_idx:
+            point = id_to_point[ordered_ids[idx]]
+            text = " ".join(point.payload.get("text", "N/A").split())
+            wrapped = textwrap.fill(text, width=120, initial_indent=" " * 6, subsequent_indent=" " * 6)
+            summary.append(
+                f"    - (Score: {ev[idx]:.3f}) "
+                f"[{point.payload.get('chunk_number', 'N/A')} | {point.payload.get('filename', 'N/A')}]"
+            )
+            summary.append(f'      "{wrapped.strip()}"')
+
+    return plot_filename, "\n".join(summary), singular_info

eigenmind-0.1.0/src/eigenmind/theta.py

@@ -0,0 +1,144 @@
+"""Lovász θ approximation (subgradient) + diversity picker on the conflict graph."""
+from __future__ import annotations
+
+import numpy as np
+
+from eigenmind.defaults import (
+    THETA_DIAG_SHIFT,
+    THETA_MAX_ITERS,
+    THETA_RANK,
+    THETA_STEP0,
+)
+
+
+def build_conflict_mask(similarity_matrix: np.ndarray, threshold: float) -> np.ndarray:
+    """Conflict graph H: H_ij = 1 iff similarity ≥ threshold (no self-loops, symmetric)."""
+    H = (similarity_matrix >= threshold).astype(np.int8)
+    np.fill_diagonal(H, 0)
+    return np.maximum(H, H.T)
+
+
+def _chol_ok(A: np.ndarray) -> bool:
+    try:
+        np.linalg.cholesky(A)
+        return True
+    except np.linalg.LinAlgError:
+        return False
+
+
+def theta_subgradient_approximation(
+    conflict_mask: np.ndarray,
+    max_iters: int = THETA_MAX_ITERS,
+    step0: float = THETA_STEP0,
+    diag_shift: float = THETA_DIAG_SHIFT,
+    rank: int = THETA_RANK,
+    verbose: bool = False,
+):
+    """Subgradient approximation of Lovász θ(H) via the Lagrangian dual.
+
+    Returns (best_theta, X, Y, lam, mu, best_x):
+      - X is a PSD primal proxy (n×n);
+      - Y is a low-rank factor with X ≈ Y Y^T (used by the diversity picker).
+    """
+    n = conflict_mask.shape[0]
+    lam = np.ones(n, dtype=float)
+    mu = np.zeros((n, n), dtype=float)
+    ones = np.ones(n, dtype=float)
+
+    def build_A(lam_vec: np.ndarray, mu_mat: np.ndarray) -> np.ndarray:
+        A = np.diag(lam_vec).astype(float)
+        A = A + 0.5 * (mu_mat * conflict_mask)
+        return 0.5 * (A + A.T)
+
+    best_theta = np.inf
+    best_A = None
+    best_x = None
+
+    for k in range(1, max_iters + 1):
+        A = build_A(lam, mu)
+        if not _chol_ok(A):
+            A = A + diag_shift * np.eye(n)
+            lam = lam + diag_shift
+            if not _chol_ok(A):
+                A = A + (10.0 * diag_shift) * np.eye(n)
+                lam = lam + 10.0 * diag_shift
+
+        b = ones + lam
+        try:
+            x = 0.5 * np.linalg.solve(A, b)
+        except np.linalg.LinAlgError:
+            x = 0.5 * np.linalg.solve(A + (10.0 * diag_shift) * np.eye(n), b)
+
+        theta_k = float(b @ x - x @ (A @ x))
+        if theta_k < best_theta:
+            best_theta = theta_k
+            best_A = A.copy()
+            best_x = x.copy()
+
+        g = x - x * x
+        h = np.outer(x, x) * conflict_mask
+        t = step0 / np.sqrt(k)
+        lam = np.clip(lam - t * g, -0.9, 1e3)
+        mu = np.clip(mu + t * h, 0.0, 1e3)
+
+    A = best_A
+    try:
+        Ainv = np.linalg.inv(A)
+    except np.linalg.LinAlgError:
+        Ainv = np.linalg.pinv(A)
+    Ainv = 0.5 * (Ainv + Ainv.T)
+
+    tr = float(np.trace(Ainv))
+    X = (np.eye(n) / n) if tr <= 1e-12 else (Ainv / tr)
+
+    w, Q = np.linalg.eigh(X)
+    w = np.maximum(w, 0.0)
+    r = min(rank, n)
+    idx = np.argsort(w)[-r:]
+    Y = Q[:, idx] * np.sqrt(np.maximum(w[idx], 0.0))[None, :]
+
+    return best_theta, X, Y, lam, mu, best_x
+
+
+def theta_diversity_picker(
+    Y: np.ndarray,
+    k: int = 12,
+    seed: str = "leverage",
+    seed_index: int = 0,
+    eps: float = 1e-12,
+):
+    """Greedy farthest-point selection on the low-rank factor Y.
+
+    Returns (selected_indices, min_distances).
+    """
+    n, _ = Y.shape
+    k = min(k, n)
+    norms = np.linalg.norm(Y, axis=1)
+    Yn = Y / np.maximum(norms[:, None], eps)
+
+    if seed == "leverage":
+        U, _, _ = np.linalg.svd(Y, full_matrices=False)
+        leverage = np.sum(U * U, axis=1)
+        first = int(np.argmax(leverage))
+    elif seed == "norm":
+        first = int(np.argmax(norms))
+    elif seed == "index":
+        first = int(np.clip(seed_index, 0, n - 1))
+    else:
+        raise ValueError("seed must be 'leverage', 'norm', or 'index'")
+
+    selected = [first]
+    min_dist: list = [np.nan]
+
+    d_to_S = 1.0 - (Yn @ Yn[first])
+    d_to_S[first] = -np.inf
+
+    for _ in range(1, k):
+        nxt = int(np.argmax(d_to_S))
+        selected.append(nxt)
+        min_dist.append(float(d_to_S[nxt]))
+        d_to_new = 1.0 - (Yn @ Yn[nxt])
+        d_to_S = np.minimum(d_to_S, d_to_new)
+        d_to_S[nxt] = -np.inf
+
+    return selected, min_dist

eigenmind-0.1.0/src/eigenmind.egg-info/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: eigenmind
+Version: 0.1.0
+Summary: Eigenvalue-based graph computations for semantic chunk retrieval (similarity graph, spectral analysis, Lovász theta diversity).
+Author-email: Marion Schaeffer <marion.schaeffer@merlin-intelligence.eu>
+License: MIT
+Project-URL: Homepage, https://github.com/merlin-intelligence/eigenmind
+Project-URL: Repository, https://github.com/merlin-intelligence/eigenmind
+Project-URL: Issues, https://github.com/merlin-intelligence/eigenmind/issues
+Keywords: graph,eigenvalue,spectral-clustering,embeddings,retrieval,diversity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: viz
+Requires-Dist: matplotlib; extra == "viz"
+Dynamic: license-file
+
+# eigenmind
+Eigenmind is a decision-intelligence engine that turns tacit expert knowledge into reusable decision frameworks, ideal for data-scarce settings. Its core uses eigenvalue-based optimisation on semantic graphs.
+
+## Install
+
+```bash
+pip install git+https://github.com/merlin-intelligence/eigenmind.git
+```
+
+## Usage
+
+```python
+from eigenmind import SimilarityGraph
+
+# retrieved_points: objects with .id, .vector, .payload (e.g. Qdrant points)
+graph = SimilarityGraph(retrieved_points)
+tags = graph.selection_tags(top_k=10)  # {chunk_id: ["Singular", "Hinge", "Theta"]}
+```
+
+### Expected input data
+
+`retrieved_points` is a plain list of objects — any class works (duck-typing,
+modeled after Qdrant's point objects), each exposing:
+
+| Attribute | Type | Constraint |
+|---|---|---|
+| `.id` | hashable (`int`, `str`, `UUID`, ...) | unique across the list — used as a dict key |
+| `.vector` | sequence of floats (`list` or `np.ndarray`) | **same length for every point**, and **unit-normalized (L2 norm ≈ 1)** |
+| `.payload` | `dict` | only read by `eigenvalue_analysis`, via `.get("text")`, `.get("chunk_number")`, `.get("filename")` |
+
+The library computes cosine similarity as a plain dot product between
+vectors (`embedding_matrix @ embedding_matrix.T`) — it does **not** normalize
+your vectors for you. Passing unnormalized vectors raises a `ValueError`
+(from `build_similarity_matrix`, used internally by `SimilarityGraph` and
+`find_singular_chunks`); normalize each vector yourself first, e.g.
+`v / np.linalg.norm(v)`.
+
+A `types.SimpleNamespace(id=..., vector=..., payload={...})` is enough — no
+dependency on Qdrant is required, as shown in the test suite. Because the
+interface is duck-typed on these three attributes, results from any
+vector store (Pinecone, Weaviate, Milvus, pgvector, Chroma, ...) work as-is,
+either directly or after a thin adapter mapping their result objects to
+`.id` / `.vector` / `.payload`.
+
+`SimilarityGraph` memoizes the similarity matrix and exposes four ranking
+strategies over a set of embedded chunks:
+
+- **Singular chunks** — points at the +/- poles of the normalized Laplacian's
+  first eigenvectors (`singular.py`).
+- **Hinge ranking** — "relevant but not obvious" chunks via an ℓ∞-connectivity
+  optimizer (`connectivity.py`).
+- **Theta diversity** — a diverse subset picked via a Lovász θ approximation on
+  the conflict graph (`theta.py`).
+- **Eigenvalue analysis** — spectrum plot + most expressive chunks per
+  eigenvector, for exploratory/debugging use. Requires the `viz` extra
+  (`pip install eigenmind[viz]`).
+
+
+## Configuration
+
+Every tunable is a plain keyword argument with a default from
+[`defaults.py`](src/eigenmind/defaults.py) — override it per call/instance,
+there is no global state to mutate.
+
+| Constant | Default | Meaning | Override via |
+|---|---|---|---|
+| `SIMILARITY_THRESHOLD` | `0.65` | Minimum cosine similarity kept as an edge weight; pairs below it are zeroed out of `W`. | `SimilarityGraph(points, threshold=...)`, `build_similarity_matrix(..., threshold=...)` |
+| `THETA_CONFLICT_THRESHOLD` | `= SIMILARITY_THRESHOLD` | Similarity level above which two chunks are considered "conflicting" (same info) for the θ diversity graph. | `SimilarityGraph.conflict_mask(threshold=...)`, `build_conflict_mask(..., threshold=...)` |
+| `THETA_RANK` | `24` | Rank of the low-rank factor `Y` (`X ≈ Y Yᵀ`) used by the diversity picker — caps how many effective directions the θ approximation keeps. | `SimilarityGraph.theta_factor(rank=...)`, `theta_subgradient_approximation(..., rank=...)` |
+| `THETA_MAX_ITERS` | `400` | Number of subgradient-descent iterations for the Lovász θ approximation. | `SimilarityGraph.theta_factor(max_iters=...)`, `theta_subgradient_approximation(..., max_iters=...)` |
+| `THETA_STEP0` | `0.25` | Initial subgradient step size, decayed as `step0 / sqrt(k)` over iterations. | `SimilarityGraph.theta_factor(step0=...)`, `theta_subgradient_approximation(..., step0=...)` |
+| `THETA_DIAG_SHIFT` | `1e-2` | Diagonal regularization added when the dual matrix isn't Cholesky-decomposable (numerical stabilizer). | `SimilarityGraph.theta_factor(diag_shift=...)`, `theta_subgradient_approximation(..., diag_shift=...)` |
+
+These defaults are the values the algorithms were originally tuned against;
+adjust them if your embeddings' similarity distribution differs
+significantly (e.g. a different embedding model or normalization scheme).
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

eigenmind-0.1.0/src/eigenmind.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/eigenmind/__init__.py
+src/eigenmind/connectivity.py
+src/eigenmind/defaults.py
+src/eigenmind/py.typed
+src/eigenmind/similarity_graph.py
+src/eigenmind/singular.py
+src/eigenmind/theta.py
+src/eigenmind.egg-info/PKG-INFO
+src/eigenmind.egg-info/SOURCES.txt
+src/eigenmind.egg-info/dependency_links.txt
+src/eigenmind.egg-info/requires.txt
+src/eigenmind.egg-info/top_level.txt
+tests/test_graph_math.py

eigenmind-0.1.0/src/eigenmind.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

eigenmind-0.1.0/src/eigenmind.egg-info/requires.txt

@@ -0,0 +1,9 @@
+numpy
+scipy
+
+[dev]
+pytest
+ruff
+
+[viz]
+matplotlib

eigenmind-0.1.0/src/eigenmind.egg-info/top_level.txt

@@ -0,0 +1 @@
+eigenmind

eigenmind-0.1.0/tests/test_graph_math.py

@@ -0,0 +1,129 @@
+"""Smoke tests on the graph math modules — pure numpy, no external services needed.
+
+Run with: pytest
+"""
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import numpy as np
+
+from eigenmind.connectivity import (
+    compute_linf_connectivity_optimizer,
+    rank_relevant_but_not_obvious_chunks,
+)
+from eigenmind.similarity_graph import SimilarityGraph
+from eigenmind.singular import build_similarity_matrix, find_singular_chunks, normalized_laplacian
+from eigenmind.theta import (
+    build_conflict_mask,
+    theta_diversity_picker,
+    theta_subgradient_approximation,
+)
+
+
+def _toy_embeddings(seed: int = 0, n: int = 8, d: int = 16) -> np.ndarray:
+    rng = np.random.default_rng(seed)
+    M = rng.standard_normal((n, d))
+    M = M / np.linalg.norm(M, axis=1, keepdims=True)
+    return M
+
+
+def test_similarity_matrix_is_symmetric_with_zero_diagonal():
+    W = build_similarity_matrix(_toy_embeddings(), threshold=0.0)
+    assert W.shape == (8, 8)
+    assert np.allclose(np.diag(W), 0.0)
+    assert np.allclose(W, W.T)
+
+
+def test_build_similarity_matrix_rejects_unnormalized_vectors():
+    M = _toy_embeddings() * 3.0  # norm 3, not 1
+    try:
+        build_similarity_matrix(M, threshold=0.0)
+        raise AssertionError("expected ValueError for unnormalized vectors")
+    except ValueError as e:
+        assert "unit-normalized" in str(e)
+
+
+def test_normalized_laplacian_is_symmetric():
+    W = build_similarity_matrix(_toy_embeddings(), threshold=0.0) + 0.1
+    np.fill_diagonal(W, 0)
+    L = normalized_laplacian(W)
+    assert np.allclose(L, L.T, atol=1e-10)
+
+
+def test_linf_optimizer_in_unit_interval_or_zero():
+    W = build_similarity_matrix(_toy_embeddings(seed=1), threshold=0.0) + 0.1
+    np.fill_diagonal(W, 0)
+    x = compute_linf_connectivity_optimizer(W)
+    assert x.shape == (8,)
+    assert np.max(np.abs(x)) <= 1.0 + 1e-9
+
+
+def test_rank_returns_one_entry_per_node():
+    W = build_similarity_matrix(_toy_embeddings(seed=2), threshold=0.0) + 0.1
+    np.fill_diagonal(W, 0)
+    x = compute_linf_connectivity_optimizer(W)
+    ranking, _, _, _, _ = rank_relevant_but_not_obvious_chunks(W, x)
+    assert len(ranking) == W.shape[0]
+    assert ranking[0][1] >= ranking[-1][1]  # sorted descending by hinge
+
+
+def test_theta_pipeline_runs_end_to_end():
+    W = build_similarity_matrix(_toy_embeddings(seed=3), threshold=0.0) + 0.1
+    np.fill_diagonal(W, 0)
+    H = build_conflict_mask(W, threshold=0.5)
+    assert np.all(np.diag(H) == 0)
+    assert np.array_equal(H, H.T)
+
+    _, _, Y, _, _, _ = theta_subgradient_approximation(H, max_iters=20)
+    selected, _ = theta_diversity_picker(Y, k=4)
+    assert len(set(selected)) == 4  # picker returns distinct indices
+
+
+def _toy_points(seed: int = 0, n: int = 8):
+    """Build mock points compatible with what Qdrant returns: id, vector, payload."""
+    M = _toy_embeddings(seed=seed, n=n)
+    return [
+        SimpleNamespace(
+            id=i,
+            vector=M[i].tolist(),
+            payload={"filename": f"f{i}.pdf", "chunk_number": i, "text": f"chunk {i} text"},
+        )
+        for i in range(n)
+    ]
+
+
+def test_similarity_graph_memoizes_x_star_and_theta_factor():
+    points = _toy_points(seed=4)
+    g = SimilarityGraph(points, threshold=0.0)
+    assert g.n == 8
+    # First call computes, second returns memoized array
+    x1 = g.linf_optimizer()
+    x2 = g.linf_optimizer()
+    assert x1 is x2  # same object reference proves memoization
+
+    Y1 = g.theta_factor(max_iters=10)
+    Y2 = g.theta_factor(max_iters=10)
+    assert Y1 is Y2
+
+
+def test_singular_chunks_respects_graph_threshold_not_the_default():
+    # threshold=0.0 keeps every pairwise edge, unlike the library default (0.65).
+    # singular_chunks() must reuse SimilarityGraph.W rather than recomputing it
+    # from the module-level default threshold.
+    points = _toy_points(seed=6)
+    g = SimilarityGraph(points, threshold=0.0)
+    assert find_singular_chunks(g.points, W=g.W) == g.singular_chunks()
+    assert len(g.singular_chunks()) > 0
+
+
+def test_similarity_graph_selection_tags_aggregates_methods():
+    points = _toy_points(seed=5)
+    g = SimilarityGraph(points, threshold=0.0)
+    tags = g.selection_tags(top_k=4)
+    # Some chunks should have at least one tag
+    assert any(len(v) > 0 for v in tags.values())
+    # Tags must be a subset of the three known methods
+    allowed = {"Singular", "Hinge", "Theta"}
+    for vs in tags.values():
+        assert set(vs) <= allowed