ragx-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{ragx_cli-0.5.0 → ragx_cli-0.6.0}/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to `ragx-cli` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [0.6.0] — 2026-07-15
+
+### Changed
+
+- **`ragx-cli models` interactive flow redesigned** around context → choice → consequence →
+  commit: a machine header (RAM, platform, `llama-server`/`lms` detection) prints first;
+  the quality tier is picked from a numbered comparison table (model, size, languages,
+  context, license) and the serving engines from numbered menus with one-line tradeoffs —
+  recommended defaults marked `»`, invalid input re-prompts; a plan step (download sizes,
+  `already downloaded ✓`, config sections, re-index consequence) shows before the confirm.
+  Behavior changes: on <8 GB RAM machines an interactive pick of `balanced`/`best` is
+  confirmed and then honored instead of silently downgraded (non-interactive runs keep the
+  auto-downgrade); `--quality jina-nano` without `--embed-engine` now locks the embedding
+  engine to `llama-server` instead of erroring (an explicit `--embed-engine lm-studio`
+  still fails loud). Flags, `--json` output, and the non-interactive contract are unchanged.
+
 ## [0.5.0] — 2026-07-15
 
 ### Added

{ragx_cli-0.5.0 → ragx_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragx-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: Similarity-graph RAG CLI: index a corpus into a chunk-level embedding graph and query it
 Project-URL: Repository, https://github.com/alber70g/ragx-cli
 Project-URL: Issues, https://github.com/alber70g/ragx-cli/issues
@@ -53,6 +53,7 @@ ragx-cli index                 # chunk -> embed -> HNSW + kNN similarity graph (
 ragx-cli query "why did we switch build tools?" --json --files-only
 ragx-cli index --full          # full rebuild: re-chunk + re-embed everything
 ragx-cli models                # recommend + download an embedding/reranker combo via LM Studio
+ragx-cli --version             # version, repo, and the effective models (corpus config + ~/.ragxrc overrides)
 ```
 
 Runs against any OpenAI-compatible embedding endpoint (LM Studio, Ollama, OpenAI). Reranking
@@ -324,8 +325,19 @@ Full write-ups: `research/bge-m3-dense-q8-vs-nomic-q4-benchmark-2026-07-12-workt
 
 `ragx-cli models` recommends an embedding + reranker combo, downloads the embedding model
 **through LM Studio** (`lms get` — one download path, plays well with restricted networks),
-pre-fetches the reranker from Hugging Face, and writes both to `ragx.toml`. Interactive on a
-TTY (quality tier + engine questions, RAM auto-detected); scriptable via flags:
+pre-fetches the reranker from Hugging Face, and writes both to `ragx.toml`. On a TTY it walks
+three steps — context first, consequences before anything is written:
+
+1. **machine header** — detected RAM, platform, whether `llama-server` is on PATH and the
+   `lms` CLI was found (this is what drives the recommended defaults);
+2. **numbered menus** — the embedding tier table (model, size, languages, context, license)
+   and one menu per serving engine with a one-line tradeoff each; the recommended default is
+   marked `»` (Enter accepts), invalid input re-prompts;
+3. **plan** — what will be downloaded (or `already downloaded ✓`) with approximate sizes,
+   which config sections change, and whether a re-index is required — all shown *before*
+   the final confirm.
+
+Scriptable via flags:
 
 ```bash
 ragx-cli models                                        # interactive
@@ -335,12 +347,12 @@ ragx-cli models --quality fast --dry-run               # recommend only, change
 
 The curated catalog (every entry verified working end-to-end):
 
-| tier | embedding model | notes |
-|---|---|---|
-| `fast` | EmbeddingGemma 300M | 308M, 100+ languages, 2048-token context |
-| `balanced` | BGE-M3 | ragx's benchmarked production model (~100 languages) |
-| `best` | Qwen3-Embedding-0.6B | 100+ languages, 32K context |
-| `jina-nano` | Jina embeddings v5 nano | 239M, best-in-class sub-500M; **CC-BY-NC (non-commercial)**; llama-server engine only — LM Studio downloads it but can't serve EuroBERT |
+| tier | embedding model | size | langs | ctx | notes |
+|---|---|---|---|---|---|
+| `fast` | EmbeddingGemma 300M | 308M | 100+ | 2K | lightest; small corpora, low RAM |
+| `balanced` | BGE-M3 | 568M | ~100 | 8K | ragx's benchmarked production model |
+| `best` | Qwen3-Embedding-0.6B | 0.6B | 100+ | 32K | highest quality; slower indexing |
+| `jina-nano` | Jina embeddings v5 nano | 239M | multi | 8K | best sub-500M; **CC-BY-NC (non-commercial)**; llama-server engine only — LM Studio downloads it but can't serve EuroBERT (picking it locks the embedding engine to llama-server automatically; an explicit `--embed-engine lm-studio` still fails loud) |
 
 **Serving engines.** Embeddings run through `--embed-engine`: **`llama-server`** (default when
 llama.cpp is installed — ragx auto-spawns `llama-server --embedding` on the downloaded GGUF and
@@ -358,7 +370,9 @@ terminates it at exit; LM Studio is only the downloader) or **`lm-studio`** (LM
 
 With both engines on `llama-server` the whole stack is ragx-managed: LM Studio downloads the
 GGUFs, ragx spawns and reaps the servers, and neither LM Studio nor huggingface.co is needed
-at query time. Under 8 GB RAM the embedding tier drops to `fast`; on macOS
+at query time. Under 8 GB RAM the recommended default moves to `fast`: interactively, picking
+a heavier tier asks for confirmation and then **honors your choice**; non-interactive runs
+(`--yes`/piped) auto-downgrade to `fast` with a note, since there is nobody to ask. On macOS
 `lms get --yes` picks MLX variants where LM Studio's catalog offers them. Switching the
 embedding model invalidates the index — the command tells you to run `ragx-cli index --full`.
 `init` offers this flow as its final step; rerun `ragx-cli models` anytime to switch.

{ragx_cli-0.5.0 → ragx_cli-0.6.0}/README.md

@@ -25,6 +25,7 @@ ragx-cli index                 # chunk -> embed -> HNSW + kNN similarity graph (
 ragx-cli query "why did we switch build tools?" --json --files-only
 ragx-cli index --full          # full rebuild: re-chunk + re-embed everything
 ragx-cli models                # recommend + download an embedding/reranker combo via LM Studio
+ragx-cli --version             # version, repo, and the effective models (corpus config + ~/.ragxrc overrides)
 ```
 
 Runs against any OpenAI-compatible embedding endpoint (LM Studio, Ollama, OpenAI). Reranking
@@ -296,8 +297,19 @@ Full write-ups: `research/bge-m3-dense-q8-vs-nomic-q4-benchmark-2026-07-12-workt
 
 `ragx-cli models` recommends an embedding + reranker combo, downloads the embedding model
 **through LM Studio** (`lms get` — one download path, plays well with restricted networks),
-pre-fetches the reranker from Hugging Face, and writes both to `ragx.toml`. Interactive on a
-TTY (quality tier + engine questions, RAM auto-detected); scriptable via flags:
+pre-fetches the reranker from Hugging Face, and writes both to `ragx.toml`. On a TTY it walks
+three steps — context first, consequences before anything is written:
+
+1. **machine header** — detected RAM, platform, whether `llama-server` is on PATH and the
+   `lms` CLI was found (this is what drives the recommended defaults);
+2. **numbered menus** — the embedding tier table (model, size, languages, context, license)
+   and one menu per serving engine with a one-line tradeoff each; the recommended default is
+   marked `»` (Enter accepts), invalid input re-prompts;
+3. **plan** — what will be downloaded (or `already downloaded ✓`) with approximate sizes,
+   which config sections change, and whether a re-index is required — all shown *before*
+   the final confirm.
+
+Scriptable via flags:
 
 ```bash
 ragx-cli models                                        # interactive
@@ -307,12 +319,12 @@ ragx-cli models --quality fast --dry-run               # recommend only, change
 
 The curated catalog (every entry verified working end-to-end):
 
-| tier | embedding model | notes |
-|---|---|---|
-| `fast` | EmbeddingGemma 300M | 308M, 100+ languages, 2048-token context |
-| `balanced` | BGE-M3 | ragx's benchmarked production model (~100 languages) |
-| `best` | Qwen3-Embedding-0.6B | 100+ languages, 32K context |
-| `jina-nano` | Jina embeddings v5 nano | 239M, best-in-class sub-500M; **CC-BY-NC (non-commercial)**; llama-server engine only — LM Studio downloads it but can't serve EuroBERT |
+| tier | embedding model | size | langs | ctx | notes |
+|---|---|---|---|---|---|
+| `fast` | EmbeddingGemma 300M | 308M | 100+ | 2K | lightest; small corpora, low RAM |
+| `balanced` | BGE-M3 | 568M | ~100 | 8K | ragx's benchmarked production model |
+| `best` | Qwen3-Embedding-0.6B | 0.6B | 100+ | 32K | highest quality; slower indexing |
+| `jina-nano` | Jina embeddings v5 nano | 239M | multi | 8K | best sub-500M; **CC-BY-NC (non-commercial)**; llama-server engine only — LM Studio downloads it but can't serve EuroBERT (picking it locks the embedding engine to llama-server automatically; an explicit `--embed-engine lm-studio` still fails loud) |
 
 **Serving engines.** Embeddings run through `--embed-engine`: **`llama-server`** (default when
 llama.cpp is installed — ragx auto-spawns `llama-server --embedding` on the downloaded GGUF and
@@ -330,7 +342,9 @@ terminates it at exit; LM Studio is only the downloader) or **`lm-studio`** (LM
 
 With both engines on `llama-server` the whole stack is ragx-managed: LM Studio downloads the
 GGUFs, ragx spawns and reaps the servers, and neither LM Studio nor huggingface.co is needed
-at query time. Under 8 GB RAM the embedding tier drops to `fast`; on macOS
+at query time. Under 8 GB RAM the recommended default moves to `fast`: interactively, picking
+a heavier tier asks for confirmation and then **honors your choice**; non-interactive runs
+(`--yes`/piped) auto-downgrade to `fast` with a note, since there is nobody to ask. On macOS
 `lms get --yes` picks MLX variants where LM Studio's catalog offers them. Switching the
 embedding model invalidates the index — the command tells you to run `ragx-cli index --full`.
 `init` offers this flow as its final step; rerun `ragx-cli models` anytime to switch.

ragx_cli-0.6.0/docs/proposal-models-command-interactive-flow.md

@@ -0,0 +1,131 @@
+# Proposal: `ragx-cli models` interactive flow redesign
+
+**Status:** implemented 2026-07-15 (`cli/models_ui.py` + `cli/models_cmd.py`); kept as the
+design rationale. The open decision below was resolved as proposed: warn-and-honor
+interactively, auto-downgrade non-interactively.
+
+## Problem
+
+The current interactive flow (`src/ragx/cli/models_cmd.py:62-104`) asks all three
+questions **before** showing any of the information needed to answer them:
+
+1. **Blind prompts.** `quality (fast/balanced/best/jina-nano) [balanced]:` offers four
+   opaque words. The catalog knows each tier's model name, parameter count, languages,
+   context length, and license — none of it is shown at prompt time. Machine specs print
+   *after* the answers.
+2. **Engine prompts don't state tradeoffs.** "llama-server vs sentence-transformers"
+   means nothing unless you already know one avoids huggingface.co entirely and the
+   other needs the `[rerank]` extra. That context lives only in `--help` flag text.
+3. **Silent downgrade.** Pick `best` on a <8 GB machine and `recommend()`
+   (`catalog.py:133-135`) substitutes `fast`, telling you only afterwards. No way to
+   override or reconsider.
+4. **The jina-nano trap.** Choosing `jina-nano` with the default `lm-studio` embed
+   engine hard-errors at the end ("rerun with `--embed-engine llama-server`") — even
+   though the catalog already encodes the constraint (`requires_llama_server`) and
+   could drive the default.
+5. **Fragile input.** A typo in the free-text tier name raises `RagxError`, exit 2,
+   start over.
+6. **Consequences surface too late.** Download sizes are never shown; "your index is
+   now invalid, run `index --full`" prints *after* `ragx.toml` is written.
+
+## Proposed flow
+
+Principle: **context → choice → consequence → commit.** Detect everything first, show
+it, ask with numbered menus, and present a plan before touching anything.
+
+```
+$ ragx-cli models
+
+machine: 32 GB RAM · macOS · llama-server: on PATH · LM Studio (lms): found
+
+── Step 1/3 · embedding model ─────────────────────────────────────────
+   Determines retrieval quality. Changing it later invalidates the
+   index (full re-index required).
+
+   #  tier       model                  size  langs  ctx   notes
+   1  fast       EmbeddingGemma 300M    308M  100+   2K    lightest; small corpora, low RAM
+ » 2  balanced   BGE-M3                 568M  ~100   8K    ragx's benchmarked production model
+   3  best       Qwen3-Embedding-0.6B   0.6B  100+   32K   highest quality; slower indexing
+   4  jina-nano  Jina v5 nano           239M  multi  8K    best <500M quality · CC-BY-NC
+                                                           (non-commercial) · llama-server only
+   select 1-4 [2]:
+
+── Step 2/3 · engines ─────────────────────────────────────────────────
+   embedding serving:
+ » 1  llama-server           ragx auto-spawns llama.cpp; LM Studio only
+                             downloads (detected on PATH)
+   2  lm-studio              LM Studio app must be running to serve
+   select 1-2 [1]:
+
+   reranker:
+ » 1  llama-server           GGUF via LM Studio — no huggingface.co needed
+   2  sentence-transformers  downloads from Hugging Face; needs the
+                             ragx-cli[rerank] extra
+   select 1-2 [1]:
+
+── Step 3/3 · plan ────────────────────────────────────────────────────
+   embedding  BGE-M3 Q8 GGUF (~600 MB)          already downloaded ✓
+   reranker   bge-reranker-v2-m3 Q8 (~600 MB)   will download via LM Studio
+   config     ragx.toml → embeddings.*, rerank.* (7 keys)
+   re-index   REQUIRED — embedding model changes; run `ragx-cli index --full` after
+
+   proceed? [Y/n]:
+```
+
+### How each problem maps to a fix
+
+- **Specs shown first**, including whether `llama-server` was found on PATH — the
+  engine defaults stop being invisible magic.
+- **Numbered menus with a re-prompt loop** instead of one-shot free text. `»` marks
+  the recommended default; Enter accepts it. Invalid input re-prompts instead of
+  exiting.
+- **RAM guard becomes visible, not substituting.** On a <8 GB machine the `»` marker
+  moves to `fast` and heavy rows get a `⚠ needs ≥8 GB` annotation. If the user still
+  picks `best`, honor it after a one-line confirm — a balanced choice means respecting
+  an informed override. Non-interactive `--quality best` keeps today's auto-downgrade
+  + note (an agent can't be asked); this interactive/non-interactive asymmetry should
+  be stated in the README.
+- **jina-nano stops being a trap:** picking it prints
+  `→ embedding engine locked to llama-server (LM Studio cannot serve this model)` and
+  skips that question instead of erroring at the end.
+- **The plan step** shows download sizes, marks what is already downloaded (the
+  `_ensure_downloaded` check moves before the confirm), lists which config keys
+  change, and states the re-index consequence *before* the write.
+
+## Implementation sketch
+
+Small and contained — no behavior change for flags / `--json` / non-interactive:
+
+1. **`core/catalog.py`** — add structured fields to the choices (`params`, `context`,
+   `languages`, `download_mb`) instead of parsing prose out of `notes`.
+   Verify: existing tests pass; table renders from fields.
+2. **`cli/models_cmd.py`** — a `_pick_numbered(title, rows, default)` helper
+   (validation loop, `»` marker) replacing `typer.prompt`/`_pick_engine` in
+   interactive mode; reorder so specs + `lms`/`llama-server` detection and the
+   already-downloaded check happen before any question.
+   Verify: interactive smoke run against a scratch corpus.
+3. **`recommend()`** — split recommendation from enforcement: return annotations
+   (RAM warning, license note, engine lock) rather than silently swapping tiers in
+   interactive mode.
+   Verify: unit tests for low-RAM interactive vs non-interactive paths.
+4. **README** — update the `models` section in the same change (CLAUDE.md rule:
+   usage-visible changes ship with their docs).
+
+Estimated diff: ~150 lines, centered on `models_cmd.py`.
+
+### Rendering choice
+
+Plain f-string column alignment is enough. `rich` is already available (transitive
+dependency of typer ≥0.12) if fancier tables are ever wanted, but no new dependency
+and no speculative widgets now.
+
+### Deliberate non-goal
+
+No full TUI (arrow-key selection à la questionary). Numbered menus keep the code
+testable with piped stdin and keep the agent-first stdin/stdout contract intact.
+
+## Open decision
+
+Interactive RAM-override behavior: warn-and-honor (proposed) vs keep the current
+auto-downgrade everywhere. Proposal argues warn-and-honor interactively, downgrade
+non-interactively.

{ragx_cli-0.5.0 → ragx_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragx-cli"
-version = "0.5.0"
+version = "0.6.0"
 description = "Similarity-graph RAG CLI: index a corpus into a chunk-level embedding graph and query it"
 readme = "README.md"
 license = "MIT"

{ragx_cli-0.5.0 → ragx_cli-0.6.0}/src/ragx/cli/app.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import logging
 import sys
+from importlib import metadata
 from pathlib import Path
 
 import typer
@@ -16,6 +17,8 @@ from ragx.core.config import (
     CONFIG_FILE,
     config_path,
     db_path,
+    find_root,
+    load_rc,
     rc_path,
     require_root,
     write_default_config,
@@ -23,6 +26,8 @@ from ragx.core.config import (
 )
 from ragx.core.errors import RagxError
 
+REPO_URL = "https://github.com/alber70g/ragx-cli"
+
 app = typer.Typer(add_completion=False, no_args_is_help=True)
 config_app = typer.Typer(add_completion=False, no_args_is_help=True)
 app.add_typer(config_app, name="config")
@@ -35,6 +40,55 @@ eval_cmd.register(app)
 models_cmd.register(app)
 
 
+def _print_version() -> None:
+    try:
+        version = metadata.version("ragx-cli")
+    except metadata.PackageNotFoundError:
+        version = "unknown"
+    typer.echo(f"ragx-cli {version}")
+    typer.echo(REPO_URL)
+    root = find_root()
+    if root is not None:
+        try:
+            cfg = Config.load(root, confirm=migrate_confirm())
+            typer.echo(f"config: {config_path(root)}")
+            for section in ("embeddings", "expansion", "rerank"):
+                line = f"  {section}: {cfg.get(f'{section}.provider')}/{cfg.get(f'{section}.model')}"
+                if cfg.data[section].get("enabled") is False:
+                    line += " (disabled)"
+                typer.echo(line)
+        except RagxError as exc:
+            typer.echo(f"config: unreadable ({exc})")
+    rc = rc_path()
+    if rc.exists():
+        typer.echo(f"global: {rc}")
+        try:
+            for section, values in load_rc().items():
+                for key, value in values.items():
+                    typer.echo(f"  {section}.{key} = {value}")
+        except RagxError as exc:
+            typer.echo(f"  unreadable ({exc})")
+
+
+def _version_option(value: bool) -> None:
+    if value:
+        _print_version()
+        raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_option,
+        is_eager=True,
+        help="show version, repo, and configured models (local + ~/.ragxrc)",
+    ),
+) -> None:
+    """Similarity-graph RAG for your files."""
+
+
 def _require_root() -> Path:
     try:
         return require_root()

{ragx_cli-0.5.0 → ragx_cli-0.6.0}/src/ragx/cli/models_cmd.py

@@ -4,11 +4,13 @@ onto the main app by app.py; `init` routes here as an optional final step."""
 
 from __future__ import annotations
 
+import shutil
 import sys
 from pathlib import Path
 
 import typer
 
+from ragx.cli import models_ui as ui
 from ragx.cli.output import emit_json, fail, migrate_confirm
 from ragx.core import lmstudio
 from ragx.core.catalog import QUALITY_TIERS, detect_specs, recommend
@@ -61,27 +63,40 @@ def run_flow(
     """The actual flow, callable from `init`. Raises RagxError on failure."""
     cfg = Config.load(root, confirm=migrate_confirm())
     interactive = sys.stdin.isatty() and not yes
+    specs = detect_specs()
+    llama_found = shutil.which("llama-server") is not None
+    lms = lmstudio.find_lms() if (interactive or not dry_run) else None
+    ui.header(specs, llama_found, lms_found=None if (dry_run and not interactive) else lms is not None)
+
     if quality is None:
         if not interactive:
             raise RagxError(f"--quality required when not interactive ({'/'.join(QUALITY_TIERS)})")
-        quality = typer.prompt(f"  quality ({'/'.join(QUALITY_TIERS)})", default="balanced")
-    engine = _pick_engine(
-        "rerank engine", rerank_engine, ("llama-server", "sentence-transformers"),
-        interactive, fallback="sentence-transformers",
-    )
-    emb_engine = _pick_engine(
-        "embedding engine", embed_engine, ("llama-server", "lm-studio"),
-        interactive, fallback="lm-studio",
-    )
+        quality = ui.pick_tier(specs)
+    embedding, reranker, notes = recommend(quality, specs, enforce_ram=not interactive)
 
-    specs = detect_specs()
-    embedding, reranker, notes = recommend(quality, specs)
-    if embedding.requires_llama_server and emb_engine != "llama-server":
-        raise RagxError(
-            f"{embedding.label} can only be served by the llama-server engine "
-            "(LM Studio downloads it but cannot serve EuroBERT models) — "
-            "rerun with --embed-engine llama-server"
+    if embedding.requires_llama_server and embed_engine != "llama-server":
+        if embed_engine is not None:
+            raise RagxError(
+                f"{embedding.label} can only be served by the llama-server engine "
+                "(LM Studio downloads it but cannot serve EuroBERT models) — "
+                "rerun with --embed-engine llama-server"
+            )
+        emb_engine = "llama-server"
+        lock_note = f"embedding engine locked to llama-server — LM Studio cannot serve {embedding.label}"
+        if interactive:
+            ui.echo(f"\n   → {lock_note}")
+        else:
+            notes.append(lock_note)
+    else:
+        emb_engine = _resolve_engine(
+            "embedding engine", embed_engine, ui.EMBED_ENGINES,
+            interactive, llama_found, fallback="lm-studio",
         )
+    engine = _resolve_engine(
+        "rerank engine", rerank_engine, ui.RERANK_ENGINES,
+        interactive, llama_found, fallback="sentence-transformers",
+    )
+
     engine_desc = (
         "llama.cpp llama-server, GGUF downloaded via LM Studio — no huggingface.co needed"
         if engine == "llama-server"
@@ -90,8 +105,8 @@ def run_flow(
     emb_desc = (
         "llama-server auto-spawned by ragx" if emb_engine == "llama-server" else "served by LM Studio"
     )
-    _echo(f"machine: {specs.ram_gb:.0f} GB RAM, {'macOS' if specs.macos else sys.platform}")
-    _echo(f"embedding: {embedding.label} ({embedding.notes}) — {emb_desc}")
+    spec_line = f"{embedding.params}, {embedding.languages} languages, {embedding.context} context"
+    _echo(f"embedding: {embedding.label} ({spec_line}) — {emb_desc}")
     _echo(f"reranker:  {reranker.label} ({reranker.notes}) — via {engine_desc}")
     for note in notes:
         _echo(f"note: {note}")
@@ -100,23 +115,39 @@ def run_flow(
         _finish(json_out, embedding, reranker, notes, engine=engine, emb_engine=emb_engine,
                 downloaded=False, config_updated=False, reindex_required=False)
         return
-    if interactive and not typer.confirm("download and update ragx.toml?", default=True):
-        raise typer.Exit(code=0)
 
-    lms = lmstudio.find_lms()
     if lms is None:
         raise RagxError(INSTALL_HINT)
 
+    emb_frag = embedding.gguf_fragment if emb_engine == "llama-server" else embedding.repo_fragment
+    emb_pre = lmstudio.find_installed(lms, emb_frag)
+    rr_pre = lmstudio.find_installed(lms, reranker.gguf_fragment) if engine == "llama-server" else None
+
+    if interactive:
+        if emb_pre is not None and emb_pre.model_key == cfg.get("embeddings.model"):
+            reindex_line = "not needed — embedding model unchanged"
+        else:
+            reindex_line = "REQUIRED — embedding model changes; run `ragx-cli index --full` after"
+        ui.show_plan(embedding=embedding, reranker=reranker, emb_engine=emb_engine,
+                     rerank_engine=engine, emb_installed=emb_pre is not None,
+                     rr_installed=rr_pre is not None, reindex_line=reindex_line)
+        if not typer.confirm("   proceed — download and update ragx.toml?", default=True, err=True):
+            raise typer.Exit(code=0)
+
     embed_updates: list[tuple[str, str]]
     if emb_engine == "llama-server":
-        installed, downloaded = _ensure_downloaded(lms, embedding.gguf_ref, embedding.gguf_fragment)
+        installed, downloaded = _ensure_downloaded(
+            lms, embedding.gguf_ref, embedding.gguf_fragment, pre=emb_pre
+        )
         embed_updates = [
             ("embeddings.provider", "llama-server"),
             ("embeddings.gguf", str(lmstudio.models_root() / installed.path)),
             ("embeddings.base_url", "http://127.0.0.1:9813/v1"),
         ]
     else:
-        installed, downloaded = _ensure_downloaded(lms, embedding.ref, embedding.repo_fragment)
+        installed, downloaded = _ensure_downloaded(
+            lms, embedding.ref, embedding.repo_fragment, pre=emb_pre
+        )
         embed_updates = [
             ("embeddings.provider", "openai"),
             ("embeddings.gguf", ""),
@@ -125,7 +156,9 @@ def run_flow(
 
     rerank_updates: list[tuple[str, str]]
     if engine == "llama-server":
-        gguf_model, gguf_downloaded = _ensure_downloaded(lms, reranker.gguf_ref, reranker.gguf_fragment)
+        gguf_model, gguf_downloaded = _ensure_downloaded(
+            lms, reranker.gguf_ref, reranker.gguf_fragment, pre=rr_pre
+        )
         downloaded = downloaded or gguf_downloaded
         gguf_path = str(lmstudio.models_root() / gguf_model.path)
         rerank_updates = [("rerank.provider", "llama-server"), ("rerank.gguf", gguf_path),
@@ -156,29 +189,28 @@ def run_flow(
             model_key=installed.model_key)
 
 
-def _pick_engine(
-    label: str, value: str | None, engines: tuple[str, str], interactive: bool, *, fallback: str
+def _resolve_engine(
+    label: str, value: str | None, options: tuple[tuple[str, str], ...],
+    interactive: bool, llama_found: bool, *, fallback: str,
 ) -> str:
-    """Explicit flag wins; otherwise default to llama-server when the binary is present
-    (fully ragx-managed, no huggingface.co), falling back to `fallback`."""
+    """Explicit flag wins; interactive shows a numbered menu; otherwise default to
+    llama-server when the binary is present (fully ragx-managed, no huggingface.co),
+    falling back to `fallback`."""
+    names = tuple(name for name, _ in options)
     if value is not None:
-        if value not in engines:
-            raise RagxError(f"{label} must be one of {'/'.join(engines)}")
+        if value not in names:
+            raise RagxError(f"{label} must be one of {'/'.join(names)}")
         return value
-    import shutil
-
-    default = "llama-server" if shutil.which("llama-server") else fallback
+    default = "llama-server" if llama_found else fallback
     if interactive:
-        picked = typer.prompt(f"  {label} ({'/'.join(engines)})", default=default)
-        if picked not in engines:
-            raise RagxError(f"{label} must be one of {'/'.join(engines)}")
-        return picked
+        return ui.pick_engine(label, options, default, llama_found)
     return default
 
 
-def _ensure_downloaded(lms: str, ref: str, fragment: str):
-    """Download `ref` via LM Studio unless a model matching `fragment` is already there."""
-    installed = lmstudio.find_installed(lms, fragment)
+def _ensure_downloaded(lms: str, ref: str, fragment: str, pre: lmstudio.InstalledModel | None = None):
+    """Download `ref` via LM Studio unless a model matching `fragment` is already there
+    (`pre` = an earlier find_installed result to reuse)."""
+    installed = pre if pre is not None else lmstudio.find_installed(lms, fragment)
     if installed is not None:
         _echo(f"already downloaded: {installed.model_key}")
         return installed, False