4lt7ab-grimoire 0.0.1__tar.gz

4lt7ab_grimoire-0.0.1/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.db
+.grimoire/
+.local/

4lt7ab_grimoire-0.0.1/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: 4lt7ab-grimoire
+Version: 0.0.1
+Summary: SQLite + sqlite-vec semantic search datastore
+Requires-Python: >=3.14
+Requires-Dist: python-ulid>=3.0
+Requires-Dist: sqlite-vec>=0.1.6
+Requires-Dist: typing-extensions>=4.0
+Provides-Extra: fastembed
+Requires-Dist: fastembed>=0.4; extra == 'fastembed'
+Requires-Dist: socksio>=1.0; extra == 'fastembed'

4lt7ab_grimoire-0.0.1/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "4lt7ab-grimoire"
+version = "0.0.1"
+description = "SQLite + sqlite-vec semantic search datastore"
+requires-python = ">=3.14"
+dependencies = [
+    "python-ulid>=3.0",
+    "sqlite-vec>=0.1.6",
+    "typing-extensions>=4.0",
+]
+
+[project.optional-dependencies]
+fastembed = ["fastembed>=0.4", "socksio>=1.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/grimoire"]

4lt7ab_grimoire-0.0.1/src/grimoire/__init__.py

@@ -0,0 +1,20 @@
+from grimoire.core import Grimoire
+from grimoire.embedder import Embedder
+from grimoire.errors import (
+    GrimoireError,
+    GrimoireMismatch,
+    InvalidEmbedder,
+    SchemaVersionError,
+)
+from grimoire.models import Entry, Stats
+
+__all__ = [
+    "Embedder",
+    "Entry",
+    "Grimoire",
+    "GrimoireError",
+    "GrimoireMismatch",
+    "InvalidEmbedder",
+    "SchemaVersionError",
+    "Stats",
+]

4lt7ab_grimoire-0.0.1/src/grimoire/core.py

@@ -0,0 +1,209 @@
+import json
+import sqlite3
+import struct
+from pathlib import Path
+from typing import Any, Self
+
+import sqlite_vec
+from ulid import ULID
+
+from grimoire.embedder import Embedder
+from grimoire.models import Entry, Stats
+from grimoire.schema import bootstrap
+
+
+class Grimoire:
+    """A semantically-indexed datastore backed by one SQLite file."""
+
+    def __init__(self, *, conn: sqlite3.Connection, embedder: Embedder) -> None:
+        self._conn = conn
+        self._embedder = embedder
+
+    @classmethod
+    def open(cls, path: str | Path, *, embedder: Embedder) -> Self:
+        conn = _open_conn(str(path))
+        try:
+            bootstrap(conn, embedder)
+            return cls(conn=conn, embedder=embedder)
+        except BaseException:
+            conn.close()
+            raise
+
+    @classmethod
+    def peek(cls, path: str | Path) -> Stats | None:
+        """Read metadata and counts from a grimoire file without opening it for use.
+
+        Returns None if the file does not exist or is not a grimoire database.
+        Does not load sqlite-vec or require an embedder, so it is safe for
+        inspection (CLI `info`, model auto-detect) before deciding how to open.
+        """
+        path = Path(path)
+        if not path.exists():
+            return None
+        try:
+            conn = sqlite3.connect(path)
+            try:
+                row = conn.execute(
+                    "SELECT model, dimension FROM grimoire WHERE id = 1"
+                ).fetchone()
+                if row is None:
+                    return None
+                version = conn.execute("PRAGMA user_version").fetchone()[0]
+                count = conn.execute("SELECT COUNT(*) FROM entries").fetchone()[0]
+                kind_rows = conn.execute(
+                    "SELECT kind, COUNT(*) FROM entries GROUP BY kind ORDER BY kind"
+                ).fetchall()
+            finally:
+                conn.close()
+        except sqlite3.Error:
+            return None
+        return Stats(
+            model=row[0],
+            dimension=row[1],
+            schema_version=version,
+            entry_count=count,
+            kinds=dict(kind_rows),
+        )
+
+    def add(
+        self,
+        *,
+        kind: str,
+        content: str,
+        payload: dict[str, Any] | None = None,
+        threshold: float | None = None,
+    ) -> Entry:
+        entry_id = str(ULID())
+        vector = self._embedder.embed(content)
+        payload_json = json.dumps(payload) if payload is not None else None
+
+        with self._conn:
+            self._conn.execute(
+                """
+                INSERT INTO entries (id, kind, content, payload, threshold)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (entry_id, kind, content, payload_json, threshold),
+            )
+            self._conn.execute(
+                "INSERT INTO vectors (entry_id, kind, embedding) VALUES (?, ?, ?)",
+                (entry_id, kind, _pack(vector)),
+            )
+
+        return Entry(
+            id=entry_id,
+            kind=kind,
+            content=content,
+            payload=payload_json,
+            threshold=threshold,
+        )
+
+    def get(self, entry_id: str) -> Entry | None:
+        row = self._conn.execute(
+            "SELECT id, kind, content, payload, threshold FROM entries WHERE id = ?",
+            (entry_id,),
+        ).fetchone()
+        return _row_to_entry(row) if row is not None else None
+
+    def list(
+        self,
+        *,
+        kind: str | None = None,
+        limit: int = 100,
+        after_id: str | None = None,
+    ) -> list[Entry]:
+        sql = "SELECT id, kind, content, payload, threshold FROM entries"
+        params: list[Any] = []
+        clauses: list[str] = []
+        if kind is not None:
+            clauses.append("kind = ?")
+            params.append(kind)
+        if after_id is not None:
+            clauses.append("id > ?")
+            params.append(after_id)
+        if clauses:
+            sql += " WHERE " + " AND ".join(clauses)
+        sql += " ORDER BY id LIMIT ?"
+        params.append(limit)
+
+        rows = self._conn.execute(sql, params).fetchall()
+        return [_row_to_entry(r) for r in rows]
+
+    def delete(self, entry_id: str) -> bool:
+        with self._conn:
+            cursor = self._conn.execute("DELETE FROM entries WHERE id = ?", (entry_id,))
+            if cursor.rowcount == 0:
+                return False
+            self._conn.execute("DELETE FROM vectors WHERE entry_id = ?", (entry_id,))
+        return True
+
+    def search(
+        self,
+        query: str,
+        *,
+        kind: str | None = None,
+        k: int = 10,
+        dynamic_threshold: bool = False,
+    ) -> list[Entry]:
+        vector = self._embedder.embed(query)
+
+        sql = (
+            "SELECT e.id, e.kind, e.content, e.payload, e.threshold, v.distance "
+            "FROM vectors v JOIN entries e ON e.id = v.entry_id "
+            "WHERE v.embedding MATCH ? AND k = ?"
+        )
+        params: list[Any] = [_pack(vector), k]
+        if kind is not None:
+            sql += " AND v.kind = ?"
+            params.append(kind)
+        sql += " ORDER BY v.distance"
+
+        rows = self._conn.execute(sql, params).fetchall()
+        results = [
+            Entry(
+                id=r[0],
+                kind=r[1],
+                content=r[2],
+                payload=r[3],
+                threshold=r[4],
+                distance=r[5],
+            )
+            for r in rows
+        ]
+        if dynamic_threshold:
+            results = [
+                r for r in results if r.threshold is None or r.distance <= r.threshold
+            ]
+        return results
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+def _open_conn(path: str) -> sqlite3.Connection:
+    conn = sqlite3.connect(path)
+    conn.enable_load_extension(True)
+    sqlite_vec.load(conn)
+    conn.enable_load_extension(False)
+    conn.execute("PRAGMA foreign_keys = ON")
+    return conn
+
+
+def _pack(vector: list[float]) -> bytes:
+    return struct.pack(f"{len(vector)}f", *vector)
+
+
+def _row_to_entry(row: tuple) -> Entry:
+    return Entry(
+        id=row[0],
+        kind=row[1],
+        content=row[2],
+        payload=row[3],
+        threshold=row[4],
+    )

4lt7ab_grimoire-0.0.1/src/grimoire/embedder.py

@@ -0,0 +1,14 @@
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Embedder(Protocol):
+    """Produces fixed-dimension vectors for text. Caller-supplied to a Grimoire."""
+
+    @property
+    def model(self) -> str: ...
+
+    @property
+    def dimension(self) -> int: ...
+
+    def embed(self, text: str) -> list[float]: ...

4lt7ab_grimoire-0.0.1/src/grimoire/embedders/__init__.py

@@ -0,0 +1,3 @@
+from grimoire.embedders.fastembed import FastembedEmbedder
+
+__all__ = ["FastembedEmbedder"]

4lt7ab_grimoire-0.0.1/src/grimoire/embedders/fastembed.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+
+
+class FastembedEmbedder:
+    """Embedder backed by Qdrant's `fastembed` library (ONNX Runtime).
+
+    Requires the optional extra: `pip install grimoire[fastembed]`.
+
+    `cache_folder` is required — the library does not pick a default
+    filesystem location on the caller's behalf.
+    """
+
+    def __init__(
+        self,
+        model_name: str = "BAAI/bge-small-en-v1.5",
+        *,
+        cache_folder: str | Path,
+        threads: int | None = None,
+    ) -> None:
+        try:
+            from fastembed import TextEmbedding
+        except ImportError as exc:
+            raise ImportError(
+                "FastembedEmbedder requires the `fastembed` extra. "
+                "Install with: pip install grimoire[fastembed]"
+            ) from exc
+
+        self._model_name = model_name
+        self._model = TextEmbedding(
+            model_name=model_name,
+            cache_dir=str(cache_folder),
+            threads=threads,
+        )
+        # Determine dimension by embedding a probe — works regardless of
+        # fastembed's internal model registry shape.
+        [probe] = list(self._model.embed(["dimension probe"]))
+        self._dimension = len(probe)
+
+    @property
+    def model(self) -> str:
+        return self._model_name
+
+    @property
+    def dimension(self) -> int:
+        return self._dimension
+
+    def embed(self, text: str) -> list[float]:
+        [vector] = list(self._model.embed([text]))
+        return vector.tolist()

4lt7ab_grimoire-0.0.1/src/grimoire/errors.py

@@ -0,0 +1,14 @@
+class GrimoireError(Exception):
+    """Base exception for all grimoire errors."""
+
+
+class GrimoireMismatch(GrimoireError):
+    """An embedder's model or dimension does not match the stored grimoire."""
+
+
+class SchemaVersionError(GrimoireError):
+    """The database file's schema version does not match what the library expects."""
+
+
+class InvalidEmbedder(GrimoireError):
+    """An embedder reported a model or dimension outside the allowed shape."""

4lt7ab_grimoire-0.0.1/src/grimoire/models.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Entry:
+    id: str
+    kind: str
+    content: str
+    payload: str | None = None
+    threshold: float | None = None
+    distance: float | None = None
+
+
+@dataclass
+class Stats:
+    model: str
+    dimension: int
+    schema_version: int
+    entry_count: int
+    kinds: dict[str, int] = field(default_factory=dict)

4lt7ab_grimoire-0.0.1/src/grimoire/schema.py

@@ -0,0 +1,71 @@
+import sqlite3
+
+from grimoire.embedder import Embedder
+from grimoire.errors import GrimoireMismatch, InvalidEmbedder, SchemaVersionError
+
+SCHEMA_VERSION = 1
+
+
+def bootstrap(conn: sqlite3.Connection, embedder: Embedder) -> None:
+    _validate_embedder(embedder)
+    version = conn.execute("PRAGMA user_version").fetchone()[0]
+    if version == 0:
+        conn.executescript(
+            f"""
+            CREATE TABLE grimoire (
+                id        INTEGER PRIMARY KEY CHECK (id = 1),
+                model     TEXT NOT NULL,
+                dimension INTEGER NOT NULL
+            );
+            CREATE TABLE entries (
+                id         TEXT PRIMARY KEY,
+                kind       TEXT NOT NULL,
+                content    TEXT NOT NULL,
+                payload    TEXT,
+                threshold  REAL
+            );
+            CREATE INDEX entries_kind ON entries(kind);
+            CREATE VIRTUAL TABLE vectors USING vec0(
+                entry_id  TEXT PRIMARY KEY,
+                kind      TEXT partition key,
+                embedding FLOAT[{embedder.dimension}]
+            );
+            """
+        )
+        conn.execute(
+            "INSERT INTO grimoire (id, model, dimension) VALUES (1, ?, ?)",
+            (embedder.model, embedder.dimension),
+        )
+        conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
+        conn.commit()
+        return
+    if version != SCHEMA_VERSION:
+        raise SchemaVersionError(
+            f"Database schema version is {version}, library expects {SCHEMA_VERSION}"
+        )
+    row = conn.execute("SELECT model, dimension FROM grimoire WHERE id = 1").fetchone()
+    if row is None:
+        raise SchemaVersionError("Database is missing its grimoire row")
+    stored_model, stored_dim = row
+    if stored_model != embedder.model or stored_dim != embedder.dimension:
+        raise GrimoireMismatch(
+            f"Embedder (model={embedder.model!r}, dim={embedder.dimension}) "
+            f"does not match grimoire "
+            f"(model={stored_model!r}, dim={stored_dim})"
+        )
+
+
+def _validate_embedder(embedder: Embedder) -> None:
+    if not isinstance(embedder.dimension, int) or isinstance(embedder.dimension, bool):
+        raise InvalidEmbedder(
+            f"Embedder dimension must be an int, "
+            f"got {type(embedder.dimension).__name__}"
+        )
+    if embedder.dimension <= 0:
+        raise InvalidEmbedder(
+            f"Embedder dimension must be positive, got {embedder.dimension}"
+        )
+    if not isinstance(embedder.model, str) or not embedder.model:
+        raise InvalidEmbedder(
+            f"Embedder model must be a non-empty string, got {embedder.model!r}"
+        )

4lt7ab_grimoire-0.0.1/tests/test_fastembed_embedder.py

@@ -0,0 +1,65 @@
+"""Integration tests for the FastembedEmbedder.
+
+Skipped unless the `fastembed` extra is installed:
+    uv sync --package grimoire --extra fastembed
+"""
+
+import os
+
+import pytest
+
+pytest.importorskip("fastembed")
+
+from grimoire import Grimoire  # noqa: E402
+from grimoire.embedders import FastembedEmbedder  # noqa: E402
+
+
+@pytest.fixture
+def cache_dir(tmp_path, monkeypatch):
+    """Pin the model cache to a sandbox-safe location for tests."""
+    cache = tmp_path / "fastembed_cache"
+    monkeypatch.setenv("HF_HOME", str(cache))
+    return cache
+
+
+def test_default_model_dimension(cache_dir):
+    e = FastembedEmbedder(cache_folder=cache_dir)
+    assert e.model == "BAAI/bge-small-en-v1.5"
+    assert e.dimension == 384
+
+
+def test_embed_returns_correct_length_vector(cache_dir):
+    e = FastembedEmbedder(cache_folder=cache_dir)
+    vector = e.embed("hello world")
+    assert len(vector) == e.dimension
+    assert all(isinstance(x, float) for x in vector)
+
+
+def test_round_trip_through_grimoire(tmp_path, cache_dir):
+    e = FastembedEmbedder(cache_folder=cache_dir)
+    with Grimoire.open(tmp_path / "store.db", embedder=e) as g:
+        g.add(kind="note", content="the moon is full tonight")
+        g.add(kind="note", content="dragons fly at midnight")
+
+        results = g.search("the moon is full tonight", k=2)
+        assert len(results) == 2
+        assert results[0].content == "the moon is full tonight"
+        assert results[0].distance < results[1].distance
+
+
+def test_cache_folder_pass_through(tmp_path):
+    cache = tmp_path / "models"
+    e = FastembedEmbedder(cache_folder=cache)
+    assert e.dimension == 384
+    # fastembed creates the cache directory lazily; just confirm the embedder
+    # initialized without error and the path is at least a directory or its
+    # parent exists.
+    assert cache.exists() or cache.parent.exists()
+
+
+# Skip-marker safety: ensure HF_HOME doesn't leak into other tests.
+def test_env_isolation():
+    if os.environ.get("HF_HOME"):
+        # monkeypatch.setenv from earlier fixtures restores on teardown,
+        # so this should never be set when this test runs without the fixture.
+        pass

4lt7ab_grimoire-0.0.1/tests/test_smoke.py

@@ -0,0 +1,283 @@
+import hashlib
+
+import pytest
+from grimoire import Entry, Grimoire, GrimoireMismatch, InvalidEmbedder, Stats
+
+
+class FakeEmbedder:
+    def __init__(self, model: str = "fake-v1", dimension: int = 8) -> None:
+        self._model = model
+        self._dimension = dimension
+
+    @property
+    def model(self) -> str:
+        return self._model
+
+    @property
+    def dimension(self) -> int:
+        return self._dimension
+
+    def embed(self, text: str) -> list[float]:
+        digest = hashlib.sha256(text.encode()).digest()
+        return [(b - 128) / 128.0 for b in digest[: self._dimension]]
+
+
+def test_open_creates_file_idempotently(tmp_path):
+    db = tmp_path / "store.db"
+    Grimoire.open(db, embedder=FakeEmbedder()).close()
+    Grimoire.open(db, embedder=FakeEmbedder()).close()
+    assert db.exists()
+
+
+def test_embedder_model_mismatch_raises(tmp_path):
+    db = tmp_path / "store.db"
+    Grimoire.open(db, embedder=FakeEmbedder(model="alpha")).close()
+    with pytest.raises(GrimoireMismatch):
+        Grimoire.open(db, embedder=FakeEmbedder(model="beta"))
+
+
+def test_embedder_dimension_mismatch_raises(tmp_path):
+    db = tmp_path / "store.db"
+    Grimoire.open(db, embedder=FakeEmbedder(dimension=8)).close()
+    with pytest.raises(GrimoireMismatch):
+        Grimoire.open(db, embedder=FakeEmbedder(dimension=16))
+
+
+def test_add_returns_entry(tmp_path):
+    with Grimoire.open(tmp_path / "store.db", embedder=FakeEmbedder()) as g:
+        entry = g.add(kind="note", content="the moon is full")
+        assert isinstance(entry, Entry)
+        assert entry.kind == "note"
+        assert entry.content == "the moon is full"
+
+
+def test_search_finds_exact_match_first(tmp_path):
+    with Grimoire.open(tmp_path / "store.db", embedder=FakeEmbedder()) as g:
+        g.add(kind="note", content="the moon is full")
+        g.add(kind="note", content="dragons fly at midnight")
+        g.add(kind="note", content="potions bubble in the cauldron")
+
+        results = g.search("the moon is full", k=3)
+        assert len(results) == 3
+        assert results[0].content == "the moon is full"
+        assert results[0].distance == 0.0
+
+
+def test_search_filters_by_kind(tmp_path):
+    with Grimoire.open(tmp_path / "store.db", embedder=FakeEmbedder()) as g:
+        g.add(kind="spell", content="lumos")
+        g.add(kind="potion", content="lumos")
+
+        results = g.search("lumos", kind="spell", k=10)
+        assert len(results) == 1
+        assert results[0].kind == "spell"
+
+
+def test_dynamic_threshold_drops_low_match(tmp_path):
+    with Grimoire.open(tmp_path / "store.db", embedder=FakeEmbedder()) as g:
+        g.add(kind="note", content="the moon is full", threshold=0.0)
+        g.add(kind="note", content="dragons fly at midnight", threshold=0.0)
+
+        all_results = g.search("the moon is full", k=10)
+        assert len(all_results) == 2
+
+        gated = g.search("the moon is full", k=10, dynamic_threshold=True)
+        assert len(gated) == 1
+        assert gated[0].content == "the moon is full"
+
+
+def test_two_files_are_independent(tmp_path):
+    a_path = tmp_path / "a.db"
+    b_path = tmp_path / "b.db"
+    with Grimoire.open(a_path, embedder=FakeEmbedder()) as a:
+        a.add(kind="note", content="alpha")
+    with Grimoire.open(b_path, embedder=FakeEmbedder()) as b:
+        b.add(kind="note", content="beta")
+        results = b.search("alpha", k=10)
+        assert all(r.content != "alpha" for r in results)
+
+
+def test_data_persists_across_reopens(tmp_path):
+    db = tmp_path / "store.db"
+    with Grimoire.open(db, embedder=FakeEmbedder()) as g:
+        g.add(kind="note", content="the moon is full")
+
+    with Grimoire.open(db, embedder=FakeEmbedder()) as g:
+        results = g.search("the moon is full", k=1)
+        assert len(results) == 1
+        assert results[0].content == "the moon is full"
+
+
+def test_get_returns_entry(tmp_path):
+    with Grimoire.open(tmp_path / "store.db", embedder=FakeEmbedder()) as g:
+        added = g.add(kind="note", content="lumos")
+        fetched = g.get(added.id)
+        assert fetched is not None
+        assert fetched.id == added.id
+        assert fetched.content == "lumos"
+
+
+def test_get_returns_none_for_missing_id(tmp_path):
+    with Grimoire.open(tmp_path / "store.db", embedder=FakeEmbedder()) as g:
+        assert g.get("01HXXXXXXXXXXXXXXXXXXXXXXX") is None
+
+
+def test_list_returns_all_entries_in_chronological_order(tmp_path):
+    with Grimoire.open(tmp_path / "store.db", embedder=FakeEmbedder()) as g:
+        a = g.add(kind="note", content="first")
+        b = g.add(kind="note", content="second")
+        c = g.add(kind="note", content="third")
+        results = g.list()
+        assert [r.id for r in results] == [a.id, b.id, c.id]
+
+
+def test_list_filters_by_kind(tmp_path):
+    with Grimoire.open(tmp_path / "store.db", embedder=FakeEmbedder()) as g:
+        g.add(kind="spell", content="lumos")
+        g.add(kind="potion", content="felix felicis")
+        g.add(kind="spell", content="alohomora")
+
+        spells = g.list(kind="spell")
+        assert len(spells) == 2
+        assert all(r.kind == "spell" for r in spells)
+
+
+def test_list_paginates_via_after_id(tmp_path):
+    with Grimoire.open(tmp_path / "store.db", embedder=FakeEmbedder()) as g:
+        added = [g.add(kind="note", content=f"e{i}") for i in range(5)]
+
+        page1 = g.list(limit=2)
+        assert [r.id for r in page1] == [added[0].id, added[1].id]
+
+        page2 = g.list(limit=2, after_id=page1[-1].id)
+        assert [r.id for r in page2] == [added[2].id, added[3].id]
+
+        page3 = g.list(limit=2, after_id=page2[-1].id)
+        assert [r.id for r in page3] == [added[4].id]
+
+        page4 = g.list(limit=2, after_id=page3[-1].id)
+        assert page4 == []
+
+
+def test_list_respects_limit(tmp_path):
+    with Grimoire.open(tmp_path / "store.db", embedder=FakeEmbedder()) as g:
+        for i in range(5):
+            g.add(kind="note", content=f"e{i}")
+        assert len(g.list(limit=3)) == 3
+
+
+def test_delete_removes_entry_and_vector(tmp_path):
+    with Grimoire.open(tmp_path / "store.db", embedder=FakeEmbedder()) as g:
+        added = g.add(kind="note", content="ephemeral")
+        assert g.delete(added.id) is True
+        assert g.get(added.id) is None
+
+        # Search should no longer return it.
+        results = g.search("ephemeral", k=10)
+        assert all(r.id != added.id for r in results)
+
+
+def test_delete_returns_false_for_missing_id(tmp_path):
+    with Grimoire.open(tmp_path / "store.db", embedder=FakeEmbedder()) as g:
+        assert g.delete("01HXXXXXXXXXXXXXXXXXXXXXXX") is False
+
+
+class _BadDimensionEmbedder:
+    @property
+    def model(self) -> str:
+        return "bad"
+
+    @property
+    def dimension(self):  # not annotated, returns whatever
+        return "8); DROP TABLE entries; --"
+
+    def embed(self, text: str) -> list[float]:
+        return [0.0] * 8
+
+
+class _NonPositiveDimensionEmbedder:
+    @property
+    def model(self) -> str:
+        return "bad"
+
+    @property
+    def dimension(self) -> int:
+        return 0
+
+    def embed(self, text: str) -> list[float]:
+        return []
+
+
+class _EmptyModelEmbedder:
+    @property
+    def model(self) -> str:
+        return ""
+
+    @property
+    def dimension(self) -> int:
+        return 8
+
+    def embed(self, text: str) -> list[float]:
+        return [0.0] * 8
+
+
+def test_embedder_with_non_int_dimension_rejected(tmp_path):
+    db = tmp_path / "store.db"
+    with pytest.raises(InvalidEmbedder):
+        Grimoire.open(db, embedder=_BadDimensionEmbedder())
+    assert not db.exists() or db.stat().st_size == 0
+
+
+def test_embedder_with_zero_dimension_rejected(tmp_path):
+    with pytest.raises(InvalidEmbedder):
+        Grimoire.open(tmp_path / "store.db", embedder=_NonPositiveDimensionEmbedder())
+
+
+def test_embedder_with_empty_model_rejected(tmp_path):
+    with pytest.raises(InvalidEmbedder):
+        Grimoire.open(tmp_path / "store.db", embedder=_EmptyModelEmbedder())
+
+
+# ---------- peek ----------
+
+
+def test_peek_returns_none_for_missing_file(tmp_path):
+    assert Grimoire.peek(tmp_path / "nope.db") is None
+
+
+def test_peek_returns_none_for_non_grimoire_file(tmp_path):
+    import sqlite3
+
+    db = tmp_path / "stranger.db"
+    conn = sqlite3.connect(db)
+    conn.execute("CREATE TABLE other (x INTEGER)")
+    conn.commit()
+    conn.close()
+    assert Grimoire.peek(db) is None
+
+
+def test_peek_returns_stats_for_initialized_grimoire(tmp_path):
+    db = tmp_path / "store.db"
+    with Grimoire.open(db, embedder=FakeEmbedder(model="m1", dimension=8)) as g:
+        g.add(kind="note", content="alpha")
+        g.add(kind="note", content="beta")
+        g.add(kind="spell", content="lumos")
+
+    stats = Grimoire.peek(db)
+    assert isinstance(stats, Stats)
+    assert stats.model == "m1"
+    assert stats.dimension == 8
+    assert stats.schema_version == 1
+    assert stats.entry_count == 3
+    assert stats.kinds == {"note": 2, "spell": 1}
+
+
+def test_peek_does_not_require_embedder_or_extension(tmp_path):
+    # peek must be safe on a freshly-created file from another process,
+    # without sqlite-vec or an embedder loaded.
+    db = tmp_path / "store.db"
+    Grimoire.open(db, embedder=FakeEmbedder()).close()
+    stats = Grimoire.peek(db)
+    assert stats is not None
+    assert stats.entry_count == 0
+    assert stats.kinds == {}