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

{ragx_cli-0.5.1 → 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.1 → ragx_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragx-cli
-Version: 0.5.1
+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
@@ -325,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
@@ -336,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
@@ -359,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.1 → ragx_cli-0.6.0}/README.md

@@ -297,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
@@ -308,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
@@ -331,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.1 → ragx_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragx-cli"
-version = "0.5.1"
+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.1 → 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

ragx_cli-0.6.0/src/ragx/cli/models_ui.py

@@ -0,0 +1,117 @@
+"""Interactive presentation for `ragx-cli models`: machine header, tier table,
+numbered pickers, and the pre-confirm plan. Rendering + prompting only — no
+downloads, no config writes. Everything goes to stderr (stdout stays pure for
+--json)."""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+
+from ragx.core.catalog import EMBEDDINGS, EmbeddingChoice, RerankerChoice, Specs, ram_limited
+
+EMBED_ENGINES = (
+    ("llama-server", "ragx auto-spawns llama.cpp; LM Studio only downloads"),
+    ("lm-studio", "LM Studio app must be running to serve embeddings"),
+)
+RERANK_ENGINES = (
+    ("llama-server", "GGUF via LM Studio — no huggingface.co access needed"),
+    ("sentence-transformers", "downloads from Hugging Face; needs the ragx-cli[rerank] extra"),
+)
+
+
+def echo(msg: str = "") -> None:
+    typer.echo(msg, err=True)
+
+
+def header(specs: Specs, llama_found: bool, lms_found: bool | None) -> None:
+    """One line of detected facts; lms_found=None means it wasn't looked up (dry-run)."""
+    ram = f"{specs.ram_gb:.0f} GB RAM" if specs.ram_gb else "RAM unknown"
+    parts = [
+        ram,
+        "macOS" if specs.macos else sys.platform,
+        f"llama-server: {'on PATH' if llama_found else 'not found'}",
+    ]
+    if lms_found is not None:
+        parts.append(f"LM Studio (lms): {'found' if lms_found else 'NOT FOUND'}")
+    echo("machine: " + " · ".join(parts))
+
+
+def _rule(title: str) -> None:
+    echo()
+    echo(f"── {title} " + "─" * max(4, 58 - len(title)))
+
+
+def pick_numbered(rows: list[str], default: int) -> int:
+    """Numbered menu (`»` marks the default); loops until a valid 1-based pick."""
+    for i, row in enumerate(rows, 1):
+        echo(f" {'»' if i == default else ' '} {i}  {row}")
+    while True:
+        raw = typer.prompt(f"  select 1-{len(rows)}", default=str(default), err=True).strip()
+        if raw.isdigit() and 1 <= int(raw) <= len(rows):
+            return int(raw)
+        echo(f"  enter a number between 1 and {len(rows)}")
+
+
+def pick_tier(specs: Specs) -> str:
+    limited = ram_limited(specs)
+    tiers = list(EMBEDDINGS)
+    _rule("embedding model")
+    echo("   determines retrieval quality — changing it later requires a full re-index")
+    echo()
+    echo(f"   #  {'tier':<10} {'model':<24} {'size':<5} {'langs':<6} {'ctx':<4} notes")
+    rows = []
+    for name in tiers:
+        e = EMBEDDINGS[name]
+        note = e.notes + ("  ⚠ needs ≥8 GB RAM" if limited and name in ("balanced", "best") else "")
+        rows.append(f"{e.tier:<10} {e.label:<24} {e.params:<5} {e.languages:<6} {e.context:<4} {note}")
+    default = tiers.index("fast" if limited else "balanced") + 1
+    while True:
+        tier = tiers[pick_numbered(rows, default) - 1]
+        if limited and tier in ("balanced", "best") and not typer.confirm(
+            f"  only {specs.ram_gb:.0f} GB RAM detected — {tier} may be slow here; use it anyway?",
+            default=False,
+            err=True,
+        ):
+            continue
+        return tier
+
+
+def pick_engine(label: str, options: tuple[tuple[str, str], ...], default: str, llama_found: bool) -> str:
+    _rule(label)
+    names = [name for name, _ in options]
+    rows = [
+        f"{name:<22} {desc}" + ("  (detected on PATH)" if name == "llama-server" and llama_found else "")
+        for name, desc in options
+    ]
+    return names[pick_numbered(rows, names.index(default) + 1) - 1]
+
+
+def show_plan(
+    *,
+    embedding: EmbeddingChoice,
+    reranker: RerankerChoice,
+    emb_engine: str,
+    rerank_engine: str,
+    emb_installed: bool,
+    rr_installed: bool,
+    reindex_line: str,
+) -> None:
+    _rule("plan")
+    emb_status = (
+        "already downloaded ✓" if emb_installed
+        else f"will download via LM Studio (~{embedding.download_mb} MB)"
+    )
+    if rerank_engine == "llama-server":
+        rr_status = (
+            "already downloaded ✓" if rr_installed
+            else f"will download via LM Studio (~{reranker.download_mb} MB)"
+        )
+    else:
+        rr_status = f"downloads from Hugging Face (~{reranker.download_mb} MB)"
+    echo(f"   embedding  {embedding.label:<26} via {emb_engine:<22} {emb_status}")
+    echo(f"   reranker   {reranker.label:<26} via {rerank_engine:<22} {rr_status}")
+    echo("   config     ragx.toml → embeddings.*, rerank.*")
+    echo(f"   re-index   {reindex_line}")
+    echo()

{ragx_cli-0.5.1 → ragx_cli-0.6.0}/src/ragx/core/catalog.py

@@ -18,6 +18,8 @@ from ragx.core.errors import RagxError
 
 QUALITY_TIERS = ("fast", "balanced", "best", "jina-nano")
 
+LOW_RAM_GB = 8.0
+
 
 @dataclass(frozen=True)
 class EmbeddingChoice:
@@ -27,7 +29,11 @@ class EmbeddingChoice:
     repo_fragment: str  # substring that identifies it in `lms ls --json` output
     doc_prefix: str
     query_prefix: str
-    notes: str
+    params: str  # parameter count, for display ("308M")
+    languages: str  # language coverage, for display ("100+")
+    context: str  # context window, for display ("2K")
+    download_mb: int  # approximate download size shown in the plan step
+    notes: str  # short qualitative note for the interactive picker table
     # llama-server engine: explicit GGUF repo (the catalog-id ref may resolve to MLX,
     # which llama-server can't load) + the fragment locating the downloaded .gguf file
     gguf_ref: str
@@ -42,6 +48,7 @@ class RerankerChoice:
     label: str
     model: str  # HF repo id, loadable by sentence-transformers CrossEncoder
     languages: str
+    download_mb: int  # approximate download size shown in the plan step
     notes: str
     # llama-server engine: Q8_0 GGUF downloadable via LM Studio (validated against the
     # safetensors originals — scores within ~0.5 logit, identical ordering)
@@ -57,7 +64,11 @@ EMBEDDINGS: dict[str, EmbeddingChoice] = {
         repo_fragment="embeddinggemma",
         doc_prefix="title: none | text: ",
         query_prefix="task: search result | query: ",
-        notes="308M, 100+ languages, 2048-token context",
+        params="308M",
+        languages="100+",
+        context="2K",
+        download_mb=300,
+        notes="lightest; small corpora, low RAM",
         gguf_ref="https://huggingface.co/lmstudio-community/embeddinggemma-300m-qat-GGUF",
         gguf_fragment="embeddinggemma-300m-qat",
     ),
@@ -68,7 +79,11 @@ EMBEDDINGS: dict[str, EmbeddingChoice] = {
         repo_fragment="bge-m3",
         doc_prefix="",
         query_prefix="",
-        notes="568M, ~100 languages, 8192-token context; ragx's benchmarked production model",
+        params="568M",
+        languages="~100",
+        context="8K",
+        download_mb=600,
+        notes="ragx's benchmarked production model",
         gguf_ref="https://huggingface.co/gaianet/bge-m3-GGUF",
         gguf_fragment="bge-m3",
     ),
@@ -82,7 +97,11 @@ EMBEDDINGS: dict[str, EmbeddingChoice] = {
             "Instruct: Given a web search query, retrieve relevant passages that answer "
             "the query\nQuery: "
         ),
-        notes="0.6B, 100+ languages, 32K context",
+        params="0.6B",
+        languages="100+",
+        context="32K",
+        download_mb=640,
+        notes="highest quality; slower indexing",
         gguf_ref="https://huggingface.co/Qwen/Qwen3-Embedding-0.6B-GGUF",
         gguf_fragment="qwen3-embedding-0.6b",
     ),
@@ -93,7 +112,11 @@ EMBEDDINGS: dict[str, EmbeddingChoice] = {
         repo_fragment="v5-nano-retrieval-q8_0",
         doc_prefix="Document: ",
         query_prefix="Query: ",
-        notes="239M, best-in-class sub-500M quality; CC-BY-NC license (non-commercial use only)",
+        params="239M",
+        languages="multi",
+        context="8K",
+        download_mb=250,
+        notes="best sub-500M quality; CC-BY-NC (non-commercial); llama-server only",
         gguf_ref="https://huggingface.co/jinaai/jina-embeddings-v5-text-nano-retrieval-GGUF@Q8_0",
         gguf_fragment="v5-nano-retrieval-q8_0",
         requires_llama_server=True,
@@ -104,6 +127,7 @@ RERANKER = RerankerChoice(
     label="BGE reranker v2-m3",
     model="BAAI/bge-reranker-v2-m3",
     languages="multilingual",
+    download_mb=600,
     notes="568M, multilingual; keeps the measured Dutch-query recall win",
     gguf_ref="https://huggingface.co/gpustack/bge-reranker-v2-m3-GGUF@Q8_0",
     gguf_fragment="bge-reranker-v2-m3-q8_0",
@@ -124,15 +148,33 @@ def detect_specs() -> Specs:
     return Specs(ram_gb=ram, macos=sys.platform == "darwin")
 
 
-def recommend(quality: str, specs: Specs) -> tuple[EmbeddingChoice, RerankerChoice, list[str]]:
-    """Pick an embedding + reranker combo; returns (embedding, reranker, notes)."""
+def ram_limited(specs: Specs) -> bool:
+    """True when RAM is known and below the balanced/best comfort threshold."""
+    return 0 < specs.ram_gb < LOW_RAM_GB
+
+
+def recommend(
+    quality: str, specs: Specs, *, enforce_ram: bool = True
+) -> tuple[EmbeddingChoice, RerankerChoice, list[str]]:
+    """Pick an embedding + reranker combo; returns (embedding, reranker, notes).
+
+    enforce_ram=False (interactive callers whose user already confirmed the pick)
+    keeps the requested tier on low-RAM machines and warns instead of downgrading.
+    """
     if quality not in EMBEDDINGS:
         raise RagxError(f"quality must be one of {'/'.join(QUALITY_TIERS)}, got {quality!r}")
     notes: list[str] = []
     tier = quality
-    if 0 < specs.ram_gb < 8 and tier in ("balanced", "best"):
-        notes.append(f"{specs.ram_gb:.0f} GB RAM detected — dropping to the fast embedding tier")
-        tier = "fast"
+    if ram_limited(specs) and tier in ("balanced", "best"):
+        if enforce_ram:
+            notes.append(
+                f"{specs.ram_gb:.0f} GB RAM detected — dropping to the fast embedding tier"
+            )
+            tier = "fast"
+        else:
+            notes.append(
+                f"{specs.ram_gb:.0f} GB RAM detected — the {tier} tier may be slow on this machine"
+            )
     if tier == "jina-nano":
         notes.append("jina-nano is CC-BY-NC licensed — non-commercial use only")
     return EMBEDDINGS[tier], RERANKER, notes

{ragx_cli-0.5.1 → ragx_cli-0.6.0}/tests/test_models.py

@@ -42,6 +42,15 @@ def test_recommend_downgrades_on_low_ram():
     assert emb.tier == "best"
 
 
+def test_recommend_no_enforce_warns_instead_of_downgrading():
+    emb, _, notes = recommend("best", Specs(ram_gb=4.0, macos=False), enforce_ram=False)
+    assert emb.tier == "best"
+    assert any("may be slow" in n for n in notes)
+    # plenty of RAM: no warning either way
+    _, _, notes = recommend("best", BIG, enforce_ram=False)
+    assert notes == []
+
+
 def test_recommend_rejects_unknown_quality():
     with pytest.raises(RagxError):
         recommend("ludicrous", BIG)
@@ -301,6 +310,120 @@ def test_models_rejects_unknown_engine(corpus):
     assert result.exit_code == 2
 
 
+def test_models_jina_auto_locks_embed_engine_when_unset(corpus, monkeypatch, tmp_path):
+    """quality=jina-nano without --embed-engine no longer errors: the engine is
+    locked to llama-server (the only one that can serve it)."""
+    gguf = lmstudio.InstalledModel(
+        model_key="v5-nano-retrieval", type="embedding", format="gguf",
+        path="jinaai/jina-embeddings-v5-text-nano-retrieval-GGUF/v5-nano-retrieval-Q8_0.gguf",
+        size_bytes=1,
+    )
+    monkeypatch.setattr(lmstudio, "find_lms", lambda: "/fake/lms")
+    monkeypatch.setattr(lmstudio, "find_installed", lambda lms, fragment: gguf)
+    monkeypatch.setattr(lmstudio, "models_root", lambda: tmp_path / "lmsmodels")
+    result = runner.invoke(
+        app, ["models", "--quality", "jina-nano", "--rerank-engine", "llama-server",
+              "--yes", "--json"],
+    )
+    assert result.exit_code == 0, result.output
+    doc = json.loads(result.stdout)
+    assert doc["embedding"]["engine"] == "llama-server"
+    assert any("locked" in n for n in doc["notes"])
+    cfg = Config.load(corpus)
+    assert cfg.get("embeddings.provider") == "llama-server"
+
+
+# --- interactive flow ---------------------------------------------------------
+
+
+def _script_prompts(monkeypatch, answers, confirms):
+    """Feed scripted answers into the numbered pickers and confirms; a TTY stdin
+    makes run_flow take the interactive branch (prompts never touch real stdin)."""
+    from types import SimpleNamespace
+
+    monkeypatch.setattr("sys.stdin", SimpleNamespace(isatty=lambda: True))
+    answer_iter, confirm_iter = iter(answers), iter(confirms)
+    monkeypatch.setattr("typer.prompt", lambda *a, **k: next(answer_iter))
+    monkeypatch.setattr("typer.confirm", lambda *a, **k: next(confirm_iter))
+
+
+def test_pick_numbered_reprompts_until_valid(monkeypatch):
+    from ragx.cli import models_ui
+
+    answers = iter(["9", "abc", "2"])
+    monkeypatch.setattr("typer.prompt", lambda *a, **k: next(answers))
+    assert models_ui.pick_numbered(["a", "b", "c"], default=1) == 2
+
+
+def test_pick_tier_low_ram_defaults_and_override(monkeypatch):
+    from ragx.cli import models_ui
+
+    low = Specs(ram_gb=4.0, macos=False)
+    # decline the RAM override for "best", then settle on "fast"
+    _script_prompts(monkeypatch, answers=["3", "1"], confirms=[False])
+    assert models_ui.pick_tier(low) == "fast"
+    # confirm the override: the explicit choice is honored
+    _script_prompts(monkeypatch, answers=["3"], confirms=[True])
+    assert models_ui.pick_tier(low) == "best"
+
+
+def test_models_interactive_flow_plans_then_writes(corpus, monkeypatch, capsys):
+    from ragx.cli.models_cmd import run_flow
+    from ragx.core.catalog import Specs as SpecsCls
+
+    installed = lmstudio.InstalledModel(
+        model_key="text-embedding-bge-m3", type="embedding", format="gguf",
+        path="gaianet/bge-m3-GGUF/x.gguf", size_bytes=1,
+    )
+    monkeypatch.setattr("ragx.cli.models_cmd.detect_specs", lambda: SpecsCls(32.0, True))
+    monkeypatch.setattr("shutil.which", lambda name: None)
+    monkeypatch.setattr(lmstudio, "find_lms", lambda: "/fake/lms")
+    monkeypatch.setattr(lmstudio, "find_installed", lambda lms, fragment: installed)
+    monkeypatch.setattr(
+        lmstudio, "download",
+        lambda lms, ref: pytest.fail("must not download an installed model"),
+    )
+    # tier 2 (balanced), embed engine 2 (lm-studio), rerank engine 2 (sentence-transformers)
+    _script_prompts(monkeypatch, answers=["2", "2", "2"], confirms=[True])
+
+    run_flow(corpus)
+
+    err = capsys.readouterr().err
+    assert "machine:" in err
+    assert "── embedding model" in err
+    assert "── plan" in err
+    assert "already downloaded ✓" in err
+    cfg = Config.load(corpus)
+    assert cfg.get("embeddings.model") == "text-embedding-bge-m3"
+    assert cfg.get("embeddings.provider") == "openai"
+    assert cfg.get("rerank.provider") == "sentence-transformers"
+
+
+def test_models_interactive_jina_skips_embed_engine_prompt(corpus, monkeypatch, tmp_path):
+    from ragx.cli.models_cmd import run_flow
+    from ragx.core.catalog import Specs as SpecsCls
+
+    gguf = lmstudio.InstalledModel(
+        model_key="v5-nano-retrieval", type="embedding", format="gguf",
+        path="jinaai/jina-embeddings-v5-text-nano-retrieval-GGUF/v5-nano-retrieval-Q8_0.gguf",
+        size_bytes=1,
+    )
+    monkeypatch.setattr("ragx.cli.models_cmd.detect_specs", lambda: SpecsCls(32.0, True))
+    monkeypatch.setattr("shutil.which", lambda name: None)
+    monkeypatch.setattr(lmstudio, "find_lms", lambda: "/fake/lms")
+    monkeypatch.setattr(lmstudio, "find_installed", lambda lms, fragment: gguf)
+    monkeypatch.setattr(lmstudio, "models_root", lambda: tmp_path / "lmsmodels")
+    # exactly ONE prompt expected (rerank engine) — an embed-engine prompt would
+    # exhaust the iterator and fail the test
+    _script_prompts(monkeypatch, answers=["1"], confirms=[True])
+
+    run_flow(corpus, quality="jina-nano")
+
+    cfg = Config.load(corpus)
+    assert cfg.get("embeddings.provider") == "llama-server"
+    assert cfg.get("rerank.provider") == "llama-server"
+
+
 def test_init_routes_into_models_flow(tmp_path, monkeypatch):
     called = {}
     monkeypatch.setattr(