pyqmd-mlx 0.7.0__py3-none-any.whl

pyqmd_mlx/bench/_fixture.py

@@ -0,0 +1,82 @@
+"""Loads and validates a bench fixture JSON file into plain dataclasses.
+Field names match Node's src/bench/fixtures/*.json exactly (id/query/
+type/description/expected_files/expected_in_top_k per query;
+description/version/collection at the top level) so an existing Node
+fixture can be reused verbatim -- except for structured lex:/vec:/hyde:/
+intent: multi-line queries, which aren't supported (see design spec) and
+are rejected here at load time rather than silently mis-scored later."""
+
+import json
+from dataclasses import dataclass, field
+
+_STRUCTURED_QUERY_PREFIXES = ("lex:", "vec:", "hyde:", "intent:")
+_REQUIRED_QUERY_FIELDS = ("id", "query", "expected_files", "expected_in_top_k")
+
+
+@dataclass
+class BenchQuery:
+    id: str
+    query: str
+    type: str
+    description: str
+    expected_files: list[str]
+    expected_in_top_k: int
+
+
+@dataclass
+class BenchFixture:
+    description: str
+    version: int
+    collection: str | None
+    queries: list[BenchQuery] = field(default_factory=list)
+
+
+def _is_structured_query(query_text: str) -> bool:
+    return any(
+        line.strip().lower().startswith(_STRUCTURED_QUERY_PREFIXES)
+        for line in query_text.splitlines()
+        if line.strip()
+    )
+
+
+def load_fixture(path: str) -> BenchFixture:
+    with open(path, encoding="utf-8") as f:
+        try:
+            raw = json.load(f)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid fixture JSON in {path}: {exc}") from exc
+
+    if not isinstance(raw.get("queries"), list):
+        raise ValueError(f"Invalid fixture: missing 'queries' array in {path}")
+
+    queries = []
+    for i, q in enumerate(raw["queries"]):
+        missing = [f for f in _REQUIRED_QUERY_FIELDS if f not in q]
+        if missing:
+            raise ValueError(
+                f"Invalid fixture: query at index {i} is missing required field(s): "
+                f"{', '.join(missing)}"
+            )
+        if _is_structured_query(q["query"]):
+            raise ValueError(
+                f"Query '{q['id']}' uses structured lex:/vec:/hyde:/intent: syntax, "
+                "which pyqmd's bench doesn't support yet. Rewrite it as a single "
+                "plain-text query."
+            )
+        queries.append(
+            BenchQuery(
+                id=q["id"],
+                query=q["query"],
+                type=q.get("type", ""),
+                description=q.get("description", ""),
+                expected_files=q["expected_files"],
+                expected_in_top_k=q["expected_in_top_k"],
+            )
+        )
+
+    return BenchFixture(
+        description=raw.get("description", ""),
+        version=raw.get("version", 1),
+        collection=raw.get("collection"),
+        queries=queries,
+    )

pyqmd_mlx/bench/_metrics.py

@@ -0,0 +1,101 @@
+"""Pure IR-metric functions, no I/O. Two families:
+
+- Absolute metrics (reciprocal_rank / mean_reciprocal_rank / recall_at_k /
+  ndcg_at_k) score one system against a fixed set of relevant document ids
+  -- used in qrels-mode, where curated relevance judgments exist.
+- Agreement metrics (top_k_overlap / spearman_rank_correlation) compare two
+  systems' own result lists to each other with no ground truth -- used in
+  agreement-mode, for a dataset profile with no qrels.
+"""
+
+from __future__ import annotations
+
+import math
+
+
+def reciprocal_rank(ranked_ids: list[str], relevant_ids: set[str]) -> float:
+    for i, doc_id in enumerate(ranked_ids):
+        if doc_id in relevant_ids:
+            return 1.0 / (i + 1)
+    return 0.0
+
+
+def mean_reciprocal_rank(
+    per_query_ranked_ids: list[list[str]], per_query_relevant_ids: list[set[str]]
+) -> float:
+    if not per_query_ranked_ids:
+        return 0.0
+    scores = [
+        reciprocal_rank(ranked, relevant)
+        for ranked, relevant in zip(per_query_ranked_ids, per_query_relevant_ids)
+    ]
+    return sum(scores) / len(scores)
+
+
+def recall_at_k(ranked_ids: list[str], relevant_ids: set[str], k: int) -> float:
+    if not relevant_ids:
+        return 0.0
+    found = set(ranked_ids[:k]) & relevant_ids
+    return len(found) / len(relevant_ids)
+
+
+def ndcg_at_k(ranked_ids: list[str], relevant_ids: set[str], k: int) -> float:
+    """Binary relevance nDCG: each relevant doc contributes gain 1, scored
+    by 1/log2(rank+1), normalized against the ideal ordering (all relevant
+    docs first). A relevant id repeated in ranked_ids earns gain only at
+    its first occurrence, so the score can never exceed 1."""
+    if not relevant_ids:
+        return 0.0
+
+    def dcg(ids: list[str]) -> float:
+        total = 0.0
+        credited: set[str] = set()
+        for i, doc_id in enumerate(ids[:k]):
+            if doc_id in relevant_ids and doc_id not in credited:
+                credited.add(doc_id)
+                total += 1.0 / math.log2(i + 2)  # rank is 1-indexed -> log2(rank+1)
+        return total
+
+    actual = dcg(ranked_ids)
+    ideal_ids = list(relevant_ids)[:k] + [d for d in ranked_ids if d not in relevant_ids]
+    ideal = dcg(ideal_ids)
+    return actual / ideal if ideal > 0 else 0.0
+
+
+def top_k_overlap(a_ids: list[str], b_ids: list[str], k: int) -> float:
+    a_top = set(a_ids[:k])
+    b_top = set(b_ids[:k])
+    # Denominator shrinks with however few results either side actually
+    # returned -- a fixed `k` made perfect agreement on a query with fewer
+    # than k results (e.g. a sparse corpus) mathematically unreachable, so
+    # the 0.7 threshold could fail queries that agreed completely.
+    denom = min(k, len(a_ids), len(b_ids))
+    if denom == 0:
+        return 0.0
+    return len(a_top & b_top) / denom
+
+
+def spearman_rank_correlation(a_ids: list[str], b_ids: list[str]) -> float | None:
+    """Spearman correlation over the ids both lists share -- ids unique to
+    either list are ignored, since there's nothing to compare their rank
+    against. Returns None if fewer than 2 ids are shared (correlation is
+    undefined for 0 or 1 points)."""
+    a_rank_full = {doc_id: i for i, doc_id in enumerate(a_ids)}
+    b_rank_full = {doc_id: i for i, doc_id in enumerate(b_ids)}
+    common = set(a_rank_full) & set(b_rank_full)
+
+    n = len(common)
+    if n < 2:
+        return None
+
+    # Ranks must span 0..n-1 over the common subset itself, not the ids'
+    # positions in the original (longer) lists -- using original positions
+    # let ids unique to one list shift the common ids' apparent rank gaps,
+    # producing results outside [-1, 1] and occasionally the wrong sign.
+    a_common_order = sorted(common, key=lambda d: a_rank_full[d])
+    b_common_order = sorted(common, key=lambda d: b_rank_full[d])
+    a_rank = {doc_id: i for i, doc_id in enumerate(a_common_order)}
+    b_rank = {doc_id: i for i, doc_id in enumerate(b_common_order)}
+
+    d_squared_sum = sum((a_rank[doc_id] - b_rank[doc_id]) ** 2 for doc_id in common)
+    return 1 - (6 * d_squared_sum) / (n * (n**2 - 1))

pyqmd_mlx/bench/_pathmatch.py

@@ -0,0 +1,60 @@
+"""Fuzzy path matching between search results and a bench fixture's
+expected_files, ported from Node's src/bench/score.ts (normalizePath/
+pathsMatch). Kept separate from _metrics.py so the exact-set-membership
+metric functions never need fuzzy-matching logic of their own --
+canonicalize_ranked_ids does the fuzzy resolution up front and hands
+plain exact string ids downstream."""
+
+
+def normalize_path(p: str) -> str:
+    """qmd://collection/docs/readme.md -> docs/readme.md; also lowercases
+    and trims leading/trailing slashes. A bare path (no qmd:// scheme) is
+    just lowercased and trimmed."""
+    if p.startswith("qmd://"):
+        without_scheme = p[len("qmd://") :]
+        slash_idx = without_scheme.find("/")
+        p = without_scheme[slash_idx + 1 :] if slash_idx >= 0 else without_scheme
+    return p.lower().strip("/")
+
+
+def paths_match(result: str, expected: str) -> bool:
+    """Exact match after normalization, or either string a suffix of the
+    other *at a path-segment boundary* -- lets a fixture author write a
+    bare filename ("readme.md") and match a deeper indexed path
+    ("docs/subdir/readme.md"), without also matching a different file
+    whose name merely ends with it ("docs/myreadme.md"). Node's pathsMatch
+    has no boundary check; see the bench design spec's path-matching
+    section for this intentional divergence."""
+    nr = normalize_path(result)
+    ne = normalize_path(expected)
+    if nr == ne:
+        return True
+    return nr.endswith("/" + ne) or ne.endswith("/" + nr)
+
+
+def canonicalize_ranked_ids(ranked_paths: list[str], expected_files: list[str]) -> list[str]:
+    """Rewrite each ranked result path to the exact expected_files string
+    it matches (paths_match semantics), so callers can score with plain
+    exact-set-membership afterward. Each expected_files entry is claimed
+    by at most one ranked path -- the highest-ranked one that matches it,
+    preferring an exact match over a suffix match -- so a bare-filename
+    expectation matching several indexed files is credited once. A path
+    matching no unclaimed expected_files entry is left as its own
+    normalized form -- it simply won't be a member of the caller's
+    relevant_ids set (and if that form happens to equal an already-claimed
+    id, the metrics themselves count each relevant id only once)."""
+    claimed: set[str] = set()
+    canonical = []
+    for path in ranked_paths:
+        normalized = normalize_path(path)
+        candidates = [e for e in expected_files if e not in claimed and paths_match(path, e)]
+        match = next(
+            (e for e in candidates if normalize_path(e) == normalized),
+            candidates[0] if candidates else None,
+        )
+        if match is None:
+            canonical.append(normalized)
+        else:
+            claimed.add(match)
+            canonical.append(match)
+    return canonical

pyqmd_mlx/bench/_sampling.py

@@ -0,0 +1,62 @@
+"""Model-call wrappers for bench --samples (see
+docs/specs/2026-09-25-bench-samples-design.md). Installed on a
+Store with Store.wrapping_llm_fns, so bench still measures the real
+Store.query pipeline."""
+
+import hashlib
+
+
+def salted_memo(expand_fn, salt: str):
+    """expand_fn with a fixed salt, memoized by (query, model): within one
+    sample, hybrid and full share a single draw per query. Failures aren't
+    memoized, so each backend sees the error the way it would unwrapped."""
+    memo: dict[tuple[str, str], list[str]] = {}
+
+    def expand(query: str, model: str) -> list[str]:
+        key = (query, model)
+        if key not in memo:
+            memo[key] = expand_fn(query, model, salt=salt)
+        return memo[key]
+
+    return expand
+
+
+class RerankCache:
+    """Rerank scores by (query, doc) across one bench run. Reranking is a
+    pure function of the pair, and samples share most of their candidates.
+
+    Sample 0 uses recording(): every call still reaches the reranker with
+    its full batch, so sample 0 matches a plain run. Later samples use
+    caching(), which sends only unseen docs. A cached score can differ in
+    the last bits from one computed in a different batch -- the replay
+    harness accepts the same."""
+
+    def __init__(self) -> None:
+        self._scores: dict[tuple[str, str], float] = {}
+
+    @staticmethod
+    def _key(query: str, doc: str) -> tuple[str, str]:
+        return (query, hashlib.sha1(doc.encode("utf-8")).hexdigest())
+
+    def recording(self, rerank_fn):
+        def rerank(query: str, documents: list[str], model: str) -> list[float]:
+            scores = rerank_fn(query, documents, model)
+            for doc, score in zip(documents, scores):
+                self._scores[self._key(query, doc)] = score
+            return scores
+
+        return rerank
+
+    def caching(self, rerank_fn):
+        def rerank(query: str, documents: list[str], model: str) -> list[float]:
+            keys = [self._key(query, doc) for doc in documents]
+            unseen: dict[tuple[str, str], str] = {}
+            for key, doc in zip(keys, documents):
+                if key not in self._scores:
+                    unseen.setdefault(key, doc)
+            if unseen:
+                scores = rerank_fn(query, list(unseen.values()), model)
+                self._scores.update(zip(unseen.keys(), scores))
+            return [self._scores[key] for key in keys]
+
+        return rerank

pyqmd_mlx/bench/runner.py

@@ -0,0 +1,283 @@
+"""Orchestrates a bench run: for each fixture query, calls all 4 search
+backends against the Store, scores results with pyqmd_mlx.bench._metrics, and
+aggregates per-backend averages. Ported from Node's src/bench/bench.ts,
+minus structured-query support (see design spec) and using pyqmd's own
+existing IR metrics rather than Node's bespoke precision/recall@1,3,5/F1
+set."""
+
+import time
+from collections.abc import Callable
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from functools import partial
+
+from pyqmd_mlx.bench._fixture import BenchFixture
+from pyqmd_mlx.bench._metrics import ndcg_at_k, recall_at_k, reciprocal_rank
+from pyqmd_mlx.bench._pathmatch import canonicalize_ranked_ids
+from pyqmd_mlx.bench._sampling import RerankCache, salted_memo
+from pyqmd_mlx.llm import ExpansionModelError
+from pyqmd_mlx.store import Store
+
+BACKENDS = ("bm25", "vector", "hybrid", "full")
+# Backends that expand the query, so their scores vary with the seed.
+SAMPLED_BACKENDS = ("hybrid", "full")
+_METRICS = ("recall_at_k", "mrr", "ndcg_at_k")
+
+
+@dataclass
+class BackendScore:
+    recall_at_k: float
+    mrr: float
+    ndcg_at_k: float
+    latency_ms: float
+
+
+@dataclass
+class QueryResult:
+    id: str
+    query: str
+    backends: dict[str, BackendScore] = field(default_factory=dict)
+    # bench --samples > 1 only: every draw for SAMPLED_BACKENDS, sample 0
+    # first. backends then holds their means (latency from sample 0).
+    samples: dict[str, list[BackendScore]] | None = None
+
+
+@dataclass
+class BenchResult:
+    fixture: str
+    collection: str | None
+    timestamp: str
+    results: list[QueryResult]
+    summary: dict[str, dict[str, float]]
+    samples: int = 1
+
+
+def _dedupe(paths: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out = []
+    for p in paths:
+        if p not in seen:
+            seen.add(p)
+            out.append(p)
+    return out
+
+
+def _run_bm25(store: Store, query: str, limit: int, collection: str | None) -> list[str]:
+    return [r.filepath for r in store.search_fts(query, limit=limit, collection=collection)]
+
+
+def _run_vector(store: Store, query: str, limit: int, collection: str | None) -> list[str]:
+    return [r.filepath for r in store.search_vec(query, limit=limit, collection=collection)]
+
+
+def _run_hybrid(store: Store, query: str, limit: int, collection: str | None) -> list[str]:
+    results = store.query(query, limit=limit, collection=collection, skip_rerank=True)
+    return [r.file for r in results]
+
+
+def _run_full(store: Store, query: str, limit: int, collection: str | None) -> list[str]:
+    results = store.query(query, limit=limit, collection=collection, skip_rerank=False)
+    return [r.file for r in results]
+
+
+_BACKEND_RUNNERS = {
+    "bm25": _run_bm25,
+    "vector": _run_vector,
+    "hybrid": _run_hybrid,
+    "full": _run_full,
+}
+
+
+def check_collection_ready(store: Store, collection: str | None) -> None:
+    """Fail fast, before running any queries, if there's nothing to search
+    -- mirrors Node's assertBenchCollectionReady, avoiding a wall of
+    all-zero scores when the real problem is an empty/missing index."""
+    stats = store.get_collection_document_stats()
+
+    if collection:
+        names = [c["name"] for c in store.list_collections()]
+        if collection not in names:
+            hint = (
+                f"Available: {', '.join(names)}. Run 'pyqmd ls' to inspect."
+                if names
+                else "Run 'pyqmd ls' to see available collections."
+            )
+            raise ValueError(f"Collection not found: {collection}\n{hint}")
+        if stats.get(collection, {"count": 0})["count"] == 0:
+            raise ValueError(
+                f"Collection '{collection}' has no indexed documents.\n"
+                f"Run 'pyqmd update', then 'pyqmd ls {collection}' to confirm "
+                "files are indexed before bench."
+            )
+        return
+
+    total = sum(s["count"] for s in stats.values())
+    if total == 0:
+        raise ValueError(
+            "No indexed documents found.\n"
+            "Index a collection with 'pyqmd collection add' / 'pyqmd update' "
+            "before running bench."
+        )
+
+
+def _score_backend(store: Store, backend_name: str, query, collection: str | None) -> BackendScore:
+    limit = max(query.expected_in_top_k, 10)
+    start = time.monotonic()
+    try:
+        raw_paths = _BACKEND_RUNNERS[backend_name](store, query.query, limit, collection)
+    except ExpansionModelError:
+        # A misconfigured expansion model is a setup error, not one backend
+        # being unavailable: scoring it 0 would silently skew every
+        # hybrid/full result, so let the command report it and exit.
+        raise
+    except Exception:
+        # A single backend being unavailable (e.g. no embeddings yet) must
+        # not abort the whole run -- score it 0 and keep going, matching
+        # Node's own try/catch-per-backend resilience.
+        return BackendScore(0.0, 0.0, 0.0, (time.monotonic() - start) * 1000)
+
+    latency_ms = (time.monotonic() - start) * 1000
+    ranked_ids = canonicalize_ranked_ids(_dedupe(raw_paths), query.expected_files)
+    relevant_ids = set(query.expected_files)
+
+    return BackendScore(
+        recall_at_k=recall_at_k(ranked_ids, relevant_ids, query.expected_in_top_k),
+        mrr=reciprocal_rank(ranked_ids, relevant_ids),
+        ndcg_at_k=ndcg_at_k(ranked_ids, relevant_ids, query.expected_in_top_k),
+        latency_ms=latency_ms,
+    )
+
+
+def _compute_summary(query_results: list[QueryResult]) -> dict[str, dict[str, float]]:
+    summary: dict[str, dict[str, float]] = {}
+    for name in BACKENDS:
+        scores = [qr.backends[name] for qr in query_results if name in qr.backends]
+        if not scores:
+            continue
+        summary[name] = {
+            "avg_recall_at_k": sum(s.recall_at_k for s in scores) / len(scores),
+            "avg_mrr": sum(s.mrr for s in scores) / len(scores),
+            "avg_ndcg_at_k": sum(s.ndcg_at_k for s in scores) / len(scores),
+            "avg_latency_ms": sum(s.latency_ms for s in scores) / len(scores),
+        }
+    return summary
+
+
+def _score_query(store: Store, query, collection: str | None) -> QueryResult:
+    backends = {name: _score_backend(store, name, query, collection) for name in BACKENDS}
+    return QueryResult(id=query.id, query=query.query, backends=backends)
+
+
+def _mean_score(draws: list[BackendScore]) -> BackendScore:
+    """Metric means across samples; latency from sample 0, the only run
+    with no cache hits."""
+    n = len(draws)
+    return BackendScore(
+        recall_at_k=sum(d.recall_at_k for d in draws) / n,
+        mrr=sum(d.mrr for d in draws) / n,
+        ndcg_at_k=sum(d.ndcg_at_k for d in draws) / n,
+        latency_ms=draws[0].latency_ms,
+    )
+
+
+def _sample_spread(query_results: list[QueryResult], samples: int) -> dict[str, dict[str, float]]:
+    """min_*/max_* of each sample's fixture-wide average. Per-query min/max
+    would just be 0..1; this is the spread that tells a real difference
+    between two configurations from seed noise."""
+    spread: dict[str, dict[str, float]] = {}
+    if not query_results:
+        return spread
+    for name in SAMPLED_BACKENDS:
+        entry: dict[str, float] = {}
+        for metric in _METRICS:
+            averages = [
+                sum(getattr(qr.samples[name][i], metric) for qr in query_results)
+                / len(query_results)
+                for i in range(samples)
+            ]
+            entry[f"min_{metric}"] = min(averages)
+            entry[f"max_{metric}"] = max(averages)
+        spread[name] = entry
+    return spread
+
+
+def _run_samples(
+    store: Store,
+    fixture: BenchFixture,
+    collection: str | None,
+    samples: int,
+    on_sample: Callable[[int, int], None] | None,
+) -> list[QueryResult]:
+    """Sample 0 is a plain run whose rerank scores are recorded; samples
+    1..N-1 re-run SAMPLED_BACKENDS with seed salt str(i) and cached rerank
+    scores (see docs/specs/2026-09-25-bench-samples-design.md)."""
+    rerank_cache = RerankCache()
+
+    if on_sample:
+        on_sample(1, samples)
+    with store.wrapping_llm_fns(rerank=rerank_cache.recording):
+        query_results = [_score_query(store, q, collection) for q in fixture.queries]
+    for qr in query_results:
+        qr.samples = {name: [qr.backends[name]] for name in SAMPLED_BACKENDS}
+
+    for i in range(1, samples):
+        if on_sample:
+            on_sample(i + 1, samples)
+        with store.wrapping_llm_fns(
+            expand=partial(salted_memo, salt=str(i)), rerank=rerank_cache.caching
+        ):
+            for query, qr in zip(fixture.queries, query_results):
+                for name in SAMPLED_BACKENDS:
+                    qr.samples[name].append(_score_backend(store, name, query, collection))
+
+    for qr in query_results:
+        for name in SAMPLED_BACKENDS:
+            qr.backends[name] = _mean_score(qr.samples[name])
+    return query_results
+
+
+def run_benchmark(
+    store: Store,
+    fixture: BenchFixture,
+    collection: str | None,
+    samples: int = 1,
+    on_sample: Callable[[int, int], None] | None = None,
+) -> BenchResult:
+    if samples == 1:
+        query_results = [_score_query(store, q, collection) for q in fixture.queries]
+        summary = _compute_summary(query_results)
+    else:
+        query_results = _run_samples(store, fixture, collection, samples, on_sample)
+        # Over the per-query means, avg_* is also the mean of the per-sample
+        # fixture averages (every sample scores the same queries).
+        summary = _compute_summary(query_results)
+        for name, spread in _sample_spread(query_results, samples).items():
+            summary[name].update(spread)
+
+    return BenchResult(
+        fixture="",
+        collection=collection,
+        timestamp=datetime.now(UTC).isoformat(),
+        results=query_results,
+        summary=summary,
+        samples=samples,
+    )
+
+
+def all_zero(summary: dict[str, dict[str, float]]) -> bool:
+    if not summary:
+        return False
+    return all(
+        s["avg_recall_at_k"] == 0 and s["avg_mrr"] == 0 and s["avg_ndcg_at_k"] == 0
+        for s in summary.values()
+    )
+
+
+def result_to_dict(result: BenchResult) -> dict:
+    d = asdict(result)
+    if result.samples == 1:
+        # --samples 1 JSON stays byte-identical to before the flag existed.
+        del d["samples"]
+        for qr in d["results"]:
+            del qr["samples"]
+    return d

pyqmd_mlx/cli/_db.py

@@ -0,0 +1,27 @@
+"""DB path resolution and Store lifecycle for the pyqmd CLI.
+
+Uses its own cache directory (~/.cache/pyqmd/) distinct from the live Node
+CLI's ~/.cache/qmd/, so the two tools can coexist during the transition
+without any risk of one clobbering the other's database.
+"""
+
+import os
+from pathlib import Path
+
+from pyqmd_mlx.store import Store
+
+DEFAULT_DB_PATH = Path.home() / ".cache" / "pyqmd" / "index.sqlite"
+
+# Lets a user point the CLI at a project-local or test index without any
+# command needing a --db option: every command already calls get_store()
+# with no arguments, so this env var is checked transparently here.
+DB_PATH_ENV_VAR = "PYQMD_DB"
+
+
+def get_store(db_path: str | None = None) -> Store:
+    """Open (creating parent directories if needed) the pyqmd database and
+    return a Store. Resolution order: explicit `db_path` argument, then the
+    PYQMD_DB environment variable, then DEFAULT_DB_PATH."""
+    path = Path(db_path or os.environ.get(DB_PATH_ENV_VAR) or DEFAULT_DB_PATH)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return Store(str(path))

pyqmd_mlx/cli/_errors.py

@@ -0,0 +1,48 @@
+"""Shared error handling for CLI commands: catch expected Store-boundary
+exceptions (bad input, missing resource) and exit cleanly with a one-line
+message; let anything else propagate with its real traceback, matching the
+original CLI's exitWithError pattern -- report the error, but never
+silently swallow a real bug."""
+
+import sqlite3
+from collections.abc import Callable
+from typing import TypeVar
+
+import typer
+
+from pyqmd_mlx.llm import ExpansionModelError
+
+T = TypeVar("T")
+
+EXPECTED_EXCEPTIONS = (
+    sqlite3.IntegrityError,
+    ValueError,
+    FileNotFoundError,
+    NotADirectoryError,
+    ExpansionModelError,
+)
+
+
+class CliError(Exception):
+    """An expected, user-facing failure whose stderr text is already shaped
+    to match Node qmd's: one or more lines (optionally styled via
+    pyqmd_mlx.cli._theme), printed as-is with no "Error: " prefix. Raise it
+    inside a run_or_exit callable."""
+
+    def __init__(self, *lines: str) -> None:
+        if not lines:
+            raise ValueError("CliError needs at least one line")
+        super().__init__("\n".join(lines))
+        self.lines = lines
+
+
+def run_or_exit(fn: Callable[[], T]) -> T:
+    try:
+        return fn()
+    except CliError as exc:
+        for line in exc.lines:
+            typer.echo(line, err=True)
+        raise typer.Exit(1) from exc
+    except EXPECTED_EXCEPTIONS as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(1) from exc