vecshift 0.1.0__py3-none-any.whl

vecshift/doctor/html.py

@@ -0,0 +1,493 @@
+"""Render a doctor :class:`Report` as one self-contained HTML file.
+
+The page inlines its own styles and script and fetches nothing, so it can be opened
+offline, attached to a ticket, or shared without sending data anywhere. It holds
+statistics only: no vectors and no row text.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from vecshift.doctor.findings import Finding, Report, Severity
+from vecshift.html_kit import compact, page, percent, stamp
+from vecshift.html_kit import e as _e
+from vecshift.html_kit import nice_ceiling as _nice_ceiling
+from vecshift.html_kit import rich as _rich
+
+MAX_BARS = 7
+DASH = "\u2013"  # en dash, for ranges
+
+_ICONS = {
+    Severity.ERROR: (
+        '<circle cx="12" cy="12" r="11" fill="var(--critical)"/>'
+        '<path d="M8 8l8 8M16 8l-8 8" stroke="var(--on-status)" stroke-width="2.2" '
+        'stroke-linecap="round"/>'
+    ),
+    Severity.WARNING: (
+        '<path d="M12 2.5 23 21.5H1z" fill="var(--warning)" stroke="var(--warning)" '
+        'stroke-width="1.5" stroke-linejoin="round"/>'
+        '<path d="M12 9v5.5" stroke="var(--on-warning)" stroke-width="2.2" '
+        'stroke-linecap="round"/><circle cx="12" cy="18" r="1.3" fill="var(--on-warning)"/>'
+    ),
+    Severity.INFO: (
+        '<circle cx="12" cy="12" r="11" fill="var(--info)"/>'
+        '<path d="M12 11v6" stroke="var(--surface)" stroke-width="2.2" stroke-linecap="round"/>'
+        '<circle cx="12" cy="7.5" r="1.4" fill="var(--surface)"/>'
+    ),
+    Severity.OK: (
+        '<circle cx="12" cy="12" r="11" fill="var(--good)"/>'
+        '<path d="m7.5 12.5 3 3 6-6.5" fill="none" stroke="var(--on-status)" '
+        'stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>'
+    ),
+}
+
+_LABELS = {
+    Severity.ERROR: ("Error", "Errors"),
+    Severity.WARNING: ("Warning", "Warnings"),
+    Severity.INFO: ("Info", "Info"),
+    Severity.OK: ("OK", "OK"),
+}
+
+
+def _icon(severity: Severity, large: bool = False) -> str:
+    cls = "sev sev-lg" if large else "sev"
+    return f'<svg class="{cls}" viewBox="0 0 24 24" aria-hidden="true">{_ICONS[severity]}</svg>'
+
+
+def _fmt_norm(x: float) -> str:
+    if x == 0:
+        return "0"
+    if abs(x) >= 100:
+        return f"{x:,.0f}"
+    if abs(x) >= 10:
+        return f"{x:.1f}"
+    return f"{x:.2f}"
+
+
+@dataclass(frozen=True, slots=True)
+class _Tile:
+    label: str
+    value: str
+    caption: str
+    state: Severity | None = None
+    meter: float | None = None
+
+
+def _verdict(report: Report) -> str:
+    errors = report.count(Severity.ERROR)
+    warnings = report.count(Severity.WARNING)
+
+    def n(count: int, word: str) -> str:
+        return f"{count} {word}{'' if count == 1 else 's'}"
+
+    if report.sample_rows == 0 and not errors and not warnings:
+        tone, severity = "info", Severity.INFO
+        title, text = "Nothing to inspect", "No rows were visible, so only the schema was checked."
+    elif errors:
+        tone, severity = "error", Severity.ERROR
+        title = "Not ready to migrate"
+        text = f"Fix {n(errors, 'error')} before migrating"
+        text += f", and review {n(warnings, 'warning')}." if warnings else "."
+    elif warnings:
+        tone, severity = "warning", Severity.WARNING
+        title = "Ready to migrate, with caveats"
+        text = f"Review {n(warnings, 'warning')} before migrating."
+    else:
+        tone, severity = "ok", Severity.OK
+        title = "Ready to migrate"
+        text = "No problems found in the inspected rows."
+
+    counts = "".join(
+        f"<li>{_icon(s)}<span><b>{report.count(s)}</b> "
+        f"{_LABELS[s][0 if report.count(s) == 1 else 1].lower()}</span></li>"
+        for s in (Severity.ERROR, Severity.WARNING, Severity.INFO, Severity.OK)
+    )
+    return (
+        f'<section class="card verdict" data-tone="{tone}" aria-labelledby="verdict-title">'
+        f"{_icon(severity, large=True)}"
+        f'<div><h2 id="verdict-title">{_e(title)}</h2><p>{_e(text)}</p>'
+        f'<ul class="counts" aria-label="Findings by severity">{counts}</ul></div>'
+        "</section>"
+    )
+
+
+def _tiles(report: Report) -> list[_Tile]:
+    f = report.facts
+    sample = f.get("sample", {})
+    rows = report.sample_rows
+    tiles: list[_Tile] = []
+
+    if report.estimated_rows is None:
+        tiles.append(_Tile("Rows", "Unknown", "table not analyzed yet"))
+    else:
+        exact = report.sample_method == "full table"
+        tiles.append(
+            _Tile(
+                "Rows",
+                compact(report.estimated_rows),
+                "exact count" if exact else "estimated from statistics",
+            )
+        )
+    tiles.append(_Tile("Inspected", compact(rows), report.sample_method))
+
+    dims: dict[str, int] = f.get("dimensions", {})
+    if len(dims) > 1:
+        tiles.append(
+            _Tile("Vector size", "Mixed", f"{len(dims)} sizes in the sample", Severity.ERROR)
+        )
+    elif report.declared_dimensions:
+        tiles.append(
+            _Tile(
+                "Vector size",
+                f"{report.declared_dimensions:,}",
+                f"{report.vector_type}, fixed by the schema",
+            )
+        )
+    elif dims:
+        (size,) = dims
+        tiles.append(
+            _Tile(
+                "Vector size",
+                f"{int(size):,}",
+                f"{report.vector_type}, not fixed by the schema",
+                Severity.WARNING,
+            )
+        )
+    else:
+        tiles.append(_Tile("Vector size", "—", f"{report.vector_type}, no vectors sampled"))
+
+    text_field = f.get("text_field")
+    present = sample.get("texts_present") or 0
+    if text_field is None:
+        tiles.append(_Tile("Re-embeddable", "None", "no source text column", Severity.ERROR, 0.0))
+    elif rows:
+        state = Severity.WARNING if present < rows else None
+        tiles.append(
+            _Tile(
+                "Re-embeddable",
+                percent(present, rows),
+                f"rows with text in {text_field}",
+                state,
+                present / rows,
+            )
+        )
+    else:
+        tiles.append(_Tile("Re-embeddable", "—", f"text in {text_field}"))
+
+    norms = f.get("norms")
+    if norms:
+        nonzero = norms["count"] - norms["zero"]
+        unit = norms["unit"]
+        # Zero vectors have their own finding; this tile is only about normalization.
+        norm_state = Severity.WARNING if 0 < unit < nonzero else None
+        caption = "unit-length vectors" if unit else "not normalized; fine with cosine"
+        tiles.append(
+            _Tile(
+                "Normalized",
+                percent(unit, norms["count"]),
+                caption,
+                norm_state,
+                unit / norms["count"],
+            )
+        )
+    else:
+        tiles.append(_Tile("Normalized", "—", "no vectors sampled"))
+
+    if text_field is not None and present:
+        dupes, base, what = sample.get("duplicate_texts", 0), present, "repeated texts"
+    else:
+        dupes, base, what = (
+            sample.get("duplicate_vectors", 0),
+            sample.get("vectors", 0),
+            ("repeated vectors"),
+        )
+    if base:
+        warn = any(x.id.startswith("duplicates.") for x in report.findings)
+        tiles.append(
+            _Tile(
+                "Duplicates",
+                percent(dupes, base),
+                f"{what} in the sample",
+                Severity.WARNING if warn else None,
+                dupes / base,
+            )
+        )
+    else:
+        tiles.append(_Tile("Duplicates", "—", "nothing sampled"))
+    return tiles
+
+
+def _render_tile(t: _Tile) -> str:
+    flag = ""
+    if t.state is not None:
+        flag = f'{_icon(t.state)}<span class="sr-only">{_LABELS[t.state][0]}:</span>'
+    meter = ""
+    if t.meter is not None:
+        state = {Severity.ERROR: "error", Severity.WARNING: "warning"}.get(
+            t.state or Severity.OK, "series"
+        )
+        width = max(0.0, min(1.0, t.meter)) * 100
+        meter = (
+            f'<div class="meter" data-state="{state}" aria-hidden="true">'
+            f'<span style="width:{width:.1f}%"></span></div>'
+        )
+    return (
+        f'<div class="card tile"><div class="tile-label">{flag}{_e(t.label)}</div>'
+        f'<div class="tile-value">{_e(t.value)}</div>'
+        f'<div class="tile-caption">{_e(t.caption)}</div>{meter}</div>'
+    )
+
+
+def _render_finding(finding: Finding) -> str:
+    hint = f'<p class="hint">{_rich(finding.hint)}</p>' if finding.hint else ""
+    label = _LABELS[finding.severity][0]
+    return (
+        f'<article class="card finding" data-severity="{finding.severity}">'
+        f"{_icon(finding.severity)}"
+        f'<div class="finding-head"><span class="label">{label}</span>'
+        f"<h3>{_rich(finding.title)}</h3>"
+        f'<span class="fid">{_e(finding.id)}</span></div>'
+        f"<p>{_rich(finding.detail)}</p>{hint}</article>"
+    )
+
+
+def _findings(report: Report) -> str:
+    ordered = report.sorted_findings()
+    buttons = [
+        f'<button type="button" data-filter="all" aria-pressed="true">All {len(ordered)}</button>'
+    ]
+    for s in (Severity.ERROR, Severity.WARNING, Severity.INFO, Severity.OK):
+        n = report.count(s)
+        disabled = " disabled" if n == 0 else ""
+        buttons.append(
+            f'<button type="button" data-filter="{s}" aria-pressed="false"{disabled}>'
+            f"{_LABELS[s][1]} {n}</button>"
+        )
+    return (
+        '<section aria-labelledby="findings-title"><h2 id="findings-title">Findings</h2>'
+        f'<div class="filters" role="toolbar" aria-label="Filter findings">{"".join(buttons)}</div>'
+        f'<div class="findings">{"".join(_render_finding(x) for x in ordered)}</div></section>'
+    )
+
+
+def _table(headers: tuple[str, str], rows: list[tuple[str, str]]) -> str:
+    body = "".join(f'<tr><td>{_e(a)}</td><td class="num">{_e(b)}</td></tr>' for a, b in rows)
+    return (
+        '<details class="table-view"><summary>View as table</summary>'
+        f'<div class="table-scroll"><table><thead><tr><th>{_e(headers[0])}</th>'
+        f'<th class="num">{_e(headers[1])}</th></tr></thead><tbody>{body}</tbody></table></div>'
+        "</details>"
+    )
+
+
+def _histogram(norms: dict[str, Any] | None) -> str:
+    head = (
+        "<figcaption><b>Vector lengths</b><span>L2 norm of each sampled vector. "
+        "Normalized vectors sit at 1.0.</span></figcaption>"
+    )
+    if not norms:
+        return (
+            f'<figure class="card wide">{head}<p class="statement">No vectors sampled</p></figure>'
+        )
+    lo, hi = norms["min"], norms["max"]
+    tol = norms["tolerance"]
+    if hi - lo <= 2 * tol:
+        return (
+            f'<figure class="card wide">{head}'
+            f'<p class="statement">All {norms["count"]:,} vectors have length '
+            f"{_fmt_norm(norms['median'])}</p>"
+            f'<p class="note">The spread is under ±{tol}, so there is nothing to chart.</p>'
+            "</figure>"
+        )
+
+    bins: list[dict[str, float]] = norms["histogram"]
+    peak = max(int(b["count"]) for b in bins)
+    top = _nice_ceiling(peak)
+    grid = "".join(
+        f'<div class="gridline" style="bottom:{frac * 100:.0f}%"></div>' for frac in (0.5, 1.0)
+    )
+    yaxis = "".join(
+        f'<span style="bottom:{frac * 100:.0f}%">{compact(round(top * frac))}</span>'
+        for frac in (0.0, 0.5, 1.0)
+    )
+    cells = []
+    for b in bins:
+        count = int(b["count"])
+        height = 0.0 if count == 0 else max(1.5, 100 * count / top)
+        label = f"length {_fmt_norm(b['start'])}{DASH}{_fmt_norm(b['end'])}"
+        value = f"{count:,} vector{'' if count == 1 else 's'}"
+        cells.append(
+            f'<div class="bin" tabindex="0" data-tip-value="{_e(value)}" '
+            f'data-tip-label="{_e(label)}" aria-label="{_e(value)}, {_e(label)}">'
+            f'<i style="height:{height:.2f}%"></i></div>'
+        )
+    ref = ""
+    if lo <= 1.0 <= hi:
+        x = 100 * (1.0 - lo) / (hi - lo)
+        flip = " flip" if x > 80 else ""
+        ref = (
+            f'<div class="refline{flip}" style="left:{x:.2f}%" aria-hidden="true">'
+            "<span>1.0 = unit length</span></div>"
+        )
+    plot = (
+        '<div class="hist" role="img" aria-label="Histogram of vector lengths">'
+        f'<div class="yaxis" aria-hidden="true">{yaxis}</div>'
+        f'<div class="plot">{grid}<div class="bins">{"".join(cells)}</div>{ref}</div>'
+        f'<div class="xaxis" aria-hidden="true"><span>{_fmt_norm(lo)}</span>'
+        f"<span>{_fmt_norm((lo + hi) / 2)}</span><span>{_fmt_norm(hi)}</span></div>"
+        '<div class="axis-title" aria-hidden="true">vector length</div></div>'
+    )
+    table = _table(
+        ("Length", "Vectors"),
+        [
+            (f"{_fmt_norm(b['start'])}{DASH}{_fmt_norm(b['end'])}", f"{int(b['count']):,}")
+            for b in bins
+        ],
+    )
+    return f'<figure class="card wide">{head}{plot}{table}</figure>'
+
+
+def _breakdown(
+    title: str, subtitle: str, counts: dict[str, int], noun: str, empty: str, single: str
+) -> str:
+    head = f"<figcaption><b>{_e(title)}</b><span>{_rich(subtitle)}</span></figcaption>"
+    if not counts:
+        return f'<figure class="card">{head}<p class="statement">{_e(empty)}</p></figure>'
+    total = sum(counts.values())
+    items = sorted(counts.items(), key=lambda kv: -kv[1])
+    if len(items) == 1:
+        (name, n) = items[0]
+        return (
+            f'<figure class="card">{head}<p class="statement">{_e(name)}</p>'
+            f'<p class="note">{_e(single.format(n=n))}</p></figure>'
+        )
+    if len(items) > MAX_BARS:
+        rest = sum(n for _, n in items[MAX_BARS - 1 :])
+        items = [*items[: MAX_BARS - 1], (f"Other ({len(items) - MAX_BARS + 1})", rest)]
+    peak = max(n for _, n in items)
+    rows = []
+    for name, n in items:
+        share = percent(n, total)
+        rows.append(
+            f'<div class="bar-row" tabindex="0" data-tip-value="{n:,} {noun} · {share}" '
+            f'data-tip-label="{_e(name)}" aria-label="{_e(name)}: {n:,} {noun}, {share}">'
+            f'<div class="bar-label">{_e(name)}</div><div class="bar-cell">'
+            f'<div class="bar" style="width:calc({100 * n / peak:.2f}% - 72px)"></div>'
+            f'<span class="bar-value">{n:,} · {share}</span></div></div>'
+        )
+    table = _table((title.split()[0], noun.capitalize()), [(k, f"{v:,}") for k, v in items])
+    return f'<figure class="card">{head}<div class="bars">{"".join(rows)}</div>{table}</figure>'
+
+
+def _charts(report: Report) -> str:
+    f = report.facts
+    models = f.get("models", {})
+    model_field = f.get("model_field")
+    model_sub = f"Recorded in `{model_field}`" if model_field else "Where rows record their model"
+    dims = {f"{int(k):,} dimensions": v for k, v in f.get("dimensions", {}).items()}
+    models_card = _breakdown(
+        "Models",
+        model_sub,
+        models,
+        "vectors",
+        empty="No model recorded",
+        single="The only model named by the {n:,} sampled vectors that record one.",
+    )
+    sizes_card = _breakdown(
+        "Vector sizes",
+        "Dimensions per sampled vector",
+        dims,
+        "vectors",
+        empty="No vectors sampled",
+        single="All {n:,} sampled vectors have this size.",
+    )
+    return (
+        '<section aria-labelledby="sample-title"><h2 id="sample-title">Inside the sample</h2>'
+        f'<div class="charts">{_histogram(f.get("norms"))}{models_card}{sizes_card}</div>'
+        "</section>"
+    )
+
+
+def _facts(report: Report, connection: str | None) -> str:
+    f = report.facts
+    yes_no = {True: "Yes", False: "No"}
+    if f.get("logical_replication") and f.get("has_primary_key"):
+        tracking = "Logical replication"
+    elif f.get("updated_at_field"):
+        tracking = f"Polling `{f['updated_at_field']}`"
+    else:
+        tracking = "None"
+    indexes = ", ".join(
+        f"{i['name']} ({i['method']}{', ' + i['metric'] if i.get('metric') else ''})"
+        for i in f.get("ann_indexes", [])
+    )
+    dims = (
+        f"`{report.vector_type}({report.declared_dimensions})`"
+        if report.declared_dimensions
+        else f"`{report.vector_type}` (size not fixed)"
+    )
+
+    def code(name: str | None, missing: str) -> str:
+        return f"`{name}`" if name else missing
+
+    rows: list[tuple[str, str]] = [
+        ("Column", code(report.target, "")),
+        ("Type", dims),
+        ("Source text", code(f.get("text_field"), "Not found")),
+        ("Model recorded in", code(f.get("model_field"), "Not recorded")),
+        ("Primary key", yes_no[bool(f.get("has_primary_key"))]),
+        ("Change tracking", tracking),
+        ("ANN indexes", indexes or "None"),
+        (
+            "Row-level security",
+            "Hides rows from this role" if f.get("rows_hidden_by_access_rules") else "Not limiting",
+        ),
+        ("Sampling", f"{report.sample_rows:,} rows, {report.sample_method}"),
+    ]
+    if connection:
+        rows.append(("Connection", f"`{connection}`"))
+    items = "".join(f'<div class="fact"><dt>{_e(k)}</dt><dd>{_rich(v)}</dd></div>' for k, v in rows)
+    return (
+        '<section aria-labelledby="setup-title"><h2 id="setup-title">Setup</h2>'
+        f'<dl class="card facts">{items}</dl></section>'
+    )
+
+
+def render_html(
+    report: Report,
+    *,
+    connection: str | None = None,
+    connection_kind: str | None = None,
+    version: str | None = None,
+    generated_at: datetime | None = None,
+) -> str:
+    """The report as a complete HTML document.
+
+    ``connection`` must already have its password removed.
+    """
+    when = stamp(generated_at)
+    meta = [report.store, *([connection_kind] if connection_kind else []), when]
+    tiles = "".join(_render_tile(t) for t in _tiles(report))
+    by = f"vecshift {version}" if version else "vecshift"
+    body = (
+        f"{_verdict(report)}"
+        f'<section aria-label="Key numbers"><div class="tiles">{tiles}</div></section>'
+        f"{_findings(report)}{_charts(report)}{_facts(report, connection)}"
+    )
+    footer = (
+        f"<p>Generated by {_e(by)} on {_e(when)}.</p>"
+        "<p>This report holds statistics only: no vectors and no row text. It loads nothing "
+        "from the network.</p>"
+    )
+    return page(
+        title=f"Doctor report · {report.target}",
+        product="vecshift doctor",
+        heading=report.target,
+        meta=meta,
+        body=body,
+        footer=footer,
+        generator=by,
+    )

vecshift/doctor/profile.py

@@ -0,0 +1,69 @@
+"""What a connector learns about an index, in a store-independent shape.
+
+Connectors fill in an :class:`IndexProfile`; the checks in :mod:`vecshift.doctor.checks`
+only ever look at the profile, never at the store.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class AnnIndex:
+    """An approximate-nearest-neighbour index over the vector field."""
+
+    name: str
+    method: str
+    """For example ``hnsw`` or ``ivfflat``."""
+    metric: str | None
+    """``cosine``, ``inner_product``, ``l2``, ``l1``, or ``None`` if unknown."""
+
+
+@dataclass(slots=True)
+class Sample:
+    """Statistics over a sample of rows. Vectors themselves are never fetched."""
+
+    rows: int
+    method: str
+    """How rows were chosen, for example ``"full table"`` or ``"table sample"``."""
+    null_vectors: int = 0
+    dimensions: Counter[int] = field(default_factory=Counter)
+    norms: list[float] = field(default_factory=list)
+    texts_present: int | None = None
+    """Rows with non-empty text, or ``None`` when there's no text field."""
+    duplicate_texts: int = 0
+    duplicate_vectors: int = 0
+    models: Counter[str] = field(default_factory=Counter)
+    """Recorded model per row, for rows that record one."""
+    model_source: str | None = None
+    """Where most rows record their model, for example ``metadata->>'model'``."""
+
+    @property
+    def vectors(self) -> int:
+        """Rows that have a vector."""
+        return self.rows - self.null_vectors
+
+
+@dataclass(slots=True)
+class IndexProfile:
+    """Everything the checks need to know about one vector field."""
+
+    store: str
+    target: str
+    """Human-readable location, for example ``public.documents.embedding``."""
+    vector_type: str
+    declared_dimensions: int | None
+    estimated_rows: int | None
+    sample: Sample
+    text_field: str | None = None
+    model_field: str | None = None
+    updated_at_field: str | None = None
+    has_primary_key: bool = True
+    logical_replication: bool = False
+    ann_indexes: list[AnnIndex] = field(default_factory=list)
+    max_indexable_dimensions: int | None = None
+    """The most dimensions the store can put in an ANN index, if it has a limit."""
+    rows_hidden_by_access_rules: bool = False
+    """Row-level security (or similar) may hide rows from the connecting role."""

vecshift/embeddings/__init__.py

@@ -0,0 +1,22 @@
+"""Embedding providers: turn text into vectors."""
+
+from vecshift.embeddings.cache import CachedEmbedder, EmbeddingCache
+from vecshift.embeddings.providers import (
+    EmbeddingError,
+    HashingEmbedder,
+    OpenAICompatEmbedder,
+    create_embedder,
+)
+from vecshift.embeddings.spec import ModelSpec, SpecError, parse_spec
+
+__all__ = [
+    "CachedEmbedder",
+    "EmbeddingCache",
+    "EmbeddingError",
+    "HashingEmbedder",
+    "ModelSpec",
+    "OpenAICompatEmbedder",
+    "SpecError",
+    "create_embedder",
+    "parse_spec",
+]

vecshift/embeddings/cache.py

@@ -0,0 +1,86 @@
+"""An on-disk embedding cache, so re-running a benchmark doesn't pay twice.
+
+Keys are hashes of the model configuration, the mode, and the text; the text itself is
+never stored. The cache lives in the user's cache directory, not the project.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import sqlite3
+from array import array
+from collections.abc import Sequence
+from pathlib import Path
+
+from vecshift.embeddings.providers import Embedder, EmbedMode
+
+
+def default_cache_path() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache"
+    return Path(base) / "vecshift" / "embeddings.sqlite"
+
+
+class EmbeddingCache:
+    def __init__(self, path: Path | None = None) -> None:
+        self.path = path or default_cache_path()
+        # Embeddings can be partly inverted back into text, so the cache is readable by
+        # its owner only, like ~/.ssh.
+        self.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        os.chmod(self.path.parent, 0o700)
+        self._db = sqlite3.connect(self.path)
+        os.chmod(self.path, 0o600)
+        self._db.execute(
+            "CREATE TABLE IF NOT EXISTS embeddings (key BLOB PRIMARY KEY, vector BLOB NOT NULL)"
+        )
+
+    @staticmethod
+    def key(identity: str, mode: str, text: str) -> bytes:
+        return hashlib.sha256(f"{identity}\0{mode}\0{text}".encode()).digest()
+
+    def get_many(self, keys: Sequence[bytes]) -> dict[bytes, list[float]]:
+        found: dict[bytes, list[float]] = {}
+        for i in range(0, len(keys), 500):
+            chunk = list(keys[i : i + 500])
+            placeholders = ",".join("?" * len(chunk))  # only "?" marks; values are bound
+            rows = self._db.execute(
+                f"SELECT key, vector FROM embeddings WHERE key IN ({placeholders})",  # noqa: S608
+                chunk,
+            ).fetchall()
+            for key, blob in rows:
+                found[key] = array("f", blob).tolist()
+        return found
+
+    def put_many(self, items: Sequence[tuple[bytes, Sequence[float]]]) -> None:
+        self._db.executemany(
+            "INSERT OR REPLACE INTO embeddings (key, vector) VALUES (?, ?)",
+            [(k, array("f", v).tobytes()) for k, v in items],
+        )
+        self._db.commit()
+
+    def close(self) -> None:
+        self._db.close()
+
+
+class CachedEmbedder:
+    """Wraps an embedder; only texts missing from the cache reach the provider."""
+
+    def __init__(self, inner: Embedder, cache: EmbeddingCache) -> None:
+        self.inner = inner
+        self.cache = cache
+        self.hits = 0
+        self.misses = 0
+
+    async def embed(self, texts: Sequence[str], mode: EmbedMode = "document") -> list[list[float]]:
+        identity = self.inner.spec.identity
+        keys = [EmbeddingCache.key(identity, mode, t) for t in texts]
+        found = self.cache.get_many(keys)
+        missing = [i for i, k in enumerate(keys) if k not in found]
+        self.hits += len(texts) - len(missing)
+        self.misses += len(missing)
+        if missing:
+            vectors = await self.inner.embed([texts[i] for i in missing], mode)
+            self.cache.put_many([(keys[i], v) for i, v in zip(missing, vectors, strict=True)])
+            for i, v in zip(missing, vectors, strict=True):
+                found[keys[i]] = v
+        return [found[k] for k in keys]