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

{ragx_cli-0.5.1 → ragx_cli-0.7.0}/CHANGELOG.md

@@ -4,6 +4,56 @@ 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.7.0] — 2026-09-17
+
+### Added
+
+- **`ragx-cli doctor`**: runs the configured providers for real — embeds a probe string,
+  scores a probe pair with the reranker, and checks the index manifest and corpus drift —
+  then reports every stage with an actionable hint. Starts whatever ragx manages, exactly
+  as `index`/`query` would. Exit `0` healthy, `1` a check failed, `2` doctor could not run
+  (no corpus, unreadable config); warnings (no index yet, drift, a model the server does
+  not list but may JIT-load) do not fail the run. `--json` emits `ragx.doctor.v1` with a
+  `status`/`detail`/`hint`/`elapsed_ms` entry per check.
+- **LM Studio autostart**: with `provider = "openai"` and a local `base_url`, `index`,
+  `query`, and `doctor` now run `lms server start` and `lms load <model>` before their
+  first request, so a cold machine needs no manual setup. ragx already spawned the
+  `llama-server` engines; LM Studio is an app ragx hands off to, so it is started but
+  never stopped. Only local URLs are touched (a cloud endpoint, including one set via
+  `OPENAI_BASE_URL`, is never started), an already-running server is left alone, and a
+  model that is not downloaded fails loud naming the models the machine does have.
+  Opt out with `embeddings.autostart` / `expansion.autostart` (default `true`, settable
+  machine-wide via `ragx-cli config set --global`).
+
+### Fixed
+
+- **`llama-server` returned 500 on every real query.** The server was spawned without
+  `-b`/`-ub`/`-c`, leaving llama.cpp's default 512-token physical batch in place; a rerank
+  or embedding input is non-causal and cannot be split across ubatches, so ragx's
+  ~800-token chunks overflowed it ("input is too large to process"). Two-document smoke
+  tests passed, which is why it went unnoticed. Now spawned with
+  `--parallel 1 -c 0 -b 8192 -ub 8192` — one slot with the model's full trained context.
+  Fixes the `llama-server` embedding engine at default chunk size as well as rerank.
+- **`ragx-cli models --quality balanced` could not download BGE-M3.** `gaianet/bge-m3-GGUF`
+  now answers 401 from the Hugging Face API; both refs point at `gpustack/bge-m3-GGUF@Q8_0`
+  (same model, already the catalog's reranker source, pinned to the benchmarked quant).
+
+## [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.7.0}/CLAUDE.md

@@ -27,6 +27,11 @@ API contracts for every core module. Deferred feature specs live in `docs/`.
   with the llama-server rerank engine, LM Studio is downloader-only at query time.
   Env fallbacks: `OPENAI_BASE_URL` (only while base_url is still the default) and
   `OPENAI_API_KEY` (only when `api_key_env` is unset); explicit config always wins.
+  With `provider="openai"` and a LOCAL base_url, `index`/`query`/`doctor` autostart LM
+  Studio first (`providers/lmstudio_process.py`: `lms server start` + `lms load` when the
+  model isn't in `lms ps`; never stops it — it's an app, not our child). Remote URLs and
+  `<section>.autostart=false` skip it. Tests are disarmed by an autouse conftest fixture
+  that stubs `ensure_for_section` — never let a test reach the real `lms`.
 - Machine-level provider settings live in `~/.ragxrc` (TOML; ONLY the embeddings/
   expansion/rerank sections, unknown keys fail loud). Precedence: DEFAULTS < corpus
   ragx.toml < ~/.ragxrc — the rc OVERRIDES corpus values and logs a stderr warning
@@ -63,17 +68,20 @@ src/ragx/
     indexer.py     #   run_index: discover->hash->chunk->embed->HNSW+store->kNN edges
     query.py       #   run_query: expansion->fan-out->RRF->traversal->rerank->combine; JSON serializers
     eval.py        #   recall@5/@10 + MRR over file-level ranking, injected query_fn
+    doctor.py      #   run_doctor: config/embeddings/expansion/rerank/index health checks
+                   #   (injected provider factories; backends get started here too)
     catalog.py     #   curated embedding/reranker catalog (tiers, prefixes) + spec detect
     lmstudio.py    #   `lms` CLI wrapper: find/download (`lms get --yes`)/`lms ls --json`;
                    #   LM Studio can't download plain safetensors — rerankers stay on HF
   providers/       # base.py protocols (Embedder/Generator/Reranker); openai_compat.py;
-                   # st_reranker.py; llama_process.py (managed llama-server lifecycle) +
+                   # st_reranker.py; lmstudio_process.py (LM Studio autostart);
+                   # llama_process.py (managed llama-server lifecycle) +
                    # llama_server.py (rerank) + llama_embedder.py (embeddings);
                    # registry.py factories (env-var + api_key_env resolution)
   cli/             # thin shells only: app.py (init/status/config + registration),
                    # pipeline.py (index/query), inspect_cmd.py, eval_cmd.py, models_cmd.py
-                   # (recommend/download/configure models), output.py
-tests/             # 177 tests; mocked HTTP (respx), FakeEmbedder integration tests, no live network
+                   # (recommend/download/configure models), doctor_cmd.py, output.py
+tests/             # 244 tests; mocked HTTP (respx), FakeEmbedder integration tests, no live network
 ```
 
 ## Flows
@@ -132,6 +140,10 @@ mostly on Dutch/multilingual queries. Details: `research/bge-m3-dense-q8-vs-nomi
 
 ## Gotchas
 
+- llama-server spawns MUST pass `--parallel 1 -c 0 -b/-ub 8192` (`llama_process.py`):
+  llama.cpp's default 512-token physical batch cannot hold a ~800-token chunk, and a
+  non-causal rerank/embedding input can't split across ubatches — without them every real
+  query 500s ("input is too large to process") while a 2-doc smoke test passes.
 - Reasoning models as expansion LLM: answers land in `content` only after thinking;
   expansion uses max_tokens=4096 to leave room for that. Don't lower it.
 - Changing `embeddings.model` invalidates the index; run_query fails loud on manifest
@@ -158,7 +170,7 @@ mostly on Dutch/multilingual queries. Details: `research/bge-m3-dense-q8-vs-nomi
 
 ## Dev loop
 
-`uv sync --group dev --extra rerank` · `uv run pytest -q` (177 pass, ~5 s) ·
+`uv sync --group dev --extra rerank` · `uv run pytest -q` (244 pass, ~5 s) ·
 `uv run ruff check src tests` · file soft cap ~150 lines · expected failures raise `RagxError`
 (CLI maps to exit 2). Live smoke: LM Studio must be running with the configured embedding model.
 Changes that impact usage (CLI flags, config keys/precedence, output schemas, install steps)

{ragx_cli-0.5.1 → ragx_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: ragx-cli
-Version: 0.5.1
+Version: 0.7.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 doctor                # check the configured providers start and answer, and the index matches
 ragx-cli --version             # version, repo, and the effective models (corpus config + ~/.ragxrc overrides)
 ```
 
@@ -70,6 +71,7 @@ your files (gitignore it) — like `.git/`, delete `.ragx/` and the corpus is un
   - [Does it actually help? (benchmarks)](#does-it-actually-help-benchmarks)
     - [Parameter study: what each knob actually does (2026-07)](#parameter-study-what-each-knob-actually-does-2026-07)
     - [BGE-M3 embedding study (2026-07-12)](#bge-m3-embedding-study-2026-07-12)
+  - [Checking your setup: `ragx-cli doctor`](#checking-your-setup-ragx-cli-doctor)
   - [Agent-first conventions](#agent-first-conventions)
   - [Using ragx-cli from a coding agent (CLAUDE.md / AGENTS.md)](#using-ragx-cli-from-a-coding-agent-claudemd--agentsmd)
     - [Pointing ragx-cli at your LLM — local or online](#pointing-ragx-cli-at-your-llm--local-or-online)
@@ -325,8 +327,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 +349,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 +372,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.
@@ -368,16 +383,66 @@ Why not `jina-embeddings-v5-text-nano`? Excellent model, but its EuroBERT archit
 Jina's llama.cpp fork — stock LM Studio can't load it (and the license is CC-BY-NC). See
 `research/lm-studio-model-download-api-and-curated-embedding-reranker-catalog-for-ragx-models-command.md`.
 
+## Checking your setup: `ragx-cli doctor`
+
+`ragx-cli doctor` runs the configured pipeline's providers for real — it embeds a probe string,
+scores a probe pair with the reranker, and checks the index on disk against the config — then
+reports each stage:
+
+```
+✓ config      /corpus/ragx.toml — embeddings=openai/text-embedding-bge-m3 · expansion=openai/qwen3.5-9b · rerank=sentence-transformers/BAAI/bge-reranker-v2-m3
+✗ embeddings  request to http://localhost:1234/v1/embeddings failed after 3 attempts: [Errno 61] Connection refused
+  → ragx does not start this server — launch it at http://localhost:1234/v1 (LM Studio: `lms server start`),
+    or hand the process to ragx with `ragx-cli models --embed-engine llama-server`
+✗ expansion   no server answered at http://localhost:1234/v1/models
+  → turn it off with `ragx-cli config set expansion.enabled false`
+✓ rerank      sentence-transformers/BAAI/bge-reranker-v2-m3 scored a probe pair (-8.14, 4.72)  3.1s
+✓ index       634 files, 1247 chunks, built with 'text-embedding-bge-m3', no drift
+```
+
+Exit codes: `0` healthy, `1` at least one check failed, `2` doctor itself could not run (no
+corpus, unreadable config). Warnings (no index yet, corpus drift, a model the server does not
+list but may JIT-load) do not fail the run. `--json` emits a `ragx.doctor.v1` document with a
+`status`/`detail`/`hint`/`elapsed_ms` entry per check.
+
+**Which servers does ragx start?** All of the local ones:
+
+| engine (`ragx-cli models`) | config | lifecycle |
+| --- | --- | --- |
+| `llama-server` | `provider="llama-server"` (embeddings and/or rerank) | spawned on demand from the configured GGUF and **killed at exit** — ragx owns the process |
+| `lm-studio` | `embeddings.provider="openai"` + a local `base_url` | `lms server start` + `lms load <model>` when nothing answers — LM Studio **keeps running** afterwards (it is an app, not ragx's child) |
+| `sentence-transformers` | `rerank.provider="sentence-transformers"` | in-process, no server |
+
+`index`, `query`, and `doctor` all do this before their first request, so a cold machine needs
+no manual setup. What was started is logged to stderr and shown in doctor's report:
+
+```
+✓ embeddings  started the LM Studio server on port 1234; loaded 'text-embedding-nomic-embed-text-v1.5' into LM Studio — openai/text-embedding-nomic-embed-text-v1.5 answered, dim=768  14.8s
+```
+
+Rules it follows: only a **local** `base_url` is ever touched (a cloud endpoint, including one
+set via `OPENAI_BASE_URL`, is never ragx's to start); an already-running server is left alone,
+and if LM Studio isn't installed but something else answers on that port, ragx just uses it; a
+model that isn't downloaded fails loud naming the models the machine does have. Turn it off per
+section with `ragx-cli config set embeddings.autostart false` (or machine-wide via
+`--global`) — then ragx only ever talks to servers you started.
+
+`ragx-cli models` still only downloads models and writes `ragx.toml`; it never launches
+anything. If a run dies with "connection refused", `doctor` names the stage and the fix.
+
 ## Agent-first conventions
 
 - `--json` emits exactly one JSON document on stdout (versioned schemas: `ragx.query.v1`,
-  `ragx.files.v1`, `ragx.status.v1`, `ragx.eval.v1`, `ragx.inspect.*.v1`); logs go to stderr.
+  `ragx.files.v1`, `ragx.status.v1`, `ragx.doctor.v1`, `ragx.eval.v1`, `ragx.inspect.*.v1`); logs go
+  to stderr.
 - Exit codes: `0` results, `1` success-but-empty, `2` error.
 - Every chunk carries `file`, `line_start/line_end`, `byte_start/byte_end` — agents jump to the
   exact source location and read the full text themselves (JSON chunk text is truncated).
 - `--files-only` aggregates chunk scores per file (sum of top-3) — the mode coding agents use most.
 - `ragx-cli status` includes a `drift` object (`new`/`changed`/`deleted` file counts vs the index) —
   agents check it to decide whether to run `ragx-cli index` before querying.
+- `ragx-cli doctor --json` verifies the providers answer before a batch of queries (`ok: false`
+  plus a per-check `hint` when something is down); exit `1` = a check failed.
 - `ragx-cli query -` reads the query from stdin; `ragx-cli inspect chunk|file|neighbors|communities|community`
   debugs the graph.
 
@@ -556,8 +621,8 @@ below — Enter accepts them all. With piped stdin (agents), `--yes`, or
 | `[communities]` | `resolution=1.0`, `seed=42` — recomputed every index run; changing these never invalidates the index |
 | `[fusion]` | `rrf_k=60`, `per_query_top=20` |
 | `[scoring]` | `alpha_rerank=0.6`, `beta_heat=0.25`, `gamma_vector=0.15` |
-| `[embeddings]` | `provider="openai"`, `base_url="http://localhost:1234/v1"`, prefixes for nomic-style models, `api_key_env=""` |
-| `[expansion]` | optional LLM for multi-query/HyDE; reasoning models supported (4096-token budget); `api_key_env=""` |
+| `[embeddings]` | `provider="openai"`, `base_url="http://localhost:1234/v1"`, prefixes for nomic-style models, `api_key_env=""`, `autostart=true` (start LM Studio + load the model when the URL is local) |
+| `[expansion]` | optional LLM for multi-query/HyDE; reasoning models supported (4096-token budget); `api_key_env=""`, `autostart=true` |
 | `[rerank]` | `BAAI/bge-reranker-v2-m3` via sentence-transformers (`uv tool install 'ragx-cli[rerank]'`) |
 
 ## Features & roadmap

{ragx_cli-0.5.1 → ragx_cli-0.7.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 doctor                # check the configured providers start and answer, and the index matches
 ragx-cli --version             # version, repo, and the effective models (corpus config + ~/.ragxrc overrides)
 ```
 
@@ -42,6 +43,7 @@ your files (gitignore it) — like `.git/`, delete `.ragx/` and the corpus is un
   - [Does it actually help? (benchmarks)](#does-it-actually-help-benchmarks)
     - [Parameter study: what each knob actually does (2026-07)](#parameter-study-what-each-knob-actually-does-2026-07)
     - [BGE-M3 embedding study (2026-07-12)](#bge-m3-embedding-study-2026-07-12)
+  - [Checking your setup: `ragx-cli doctor`](#checking-your-setup-ragx-cli-doctor)
   - [Agent-first conventions](#agent-first-conventions)
   - [Using ragx-cli from a coding agent (CLAUDE.md / AGENTS.md)](#using-ragx-cli-from-a-coding-agent-claudemd--agentsmd)
     - [Pointing ragx-cli at your LLM — local or online](#pointing-ragx-cli-at-your-llm--local-or-online)
@@ -297,8 +299,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 +321,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 +344,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.
@@ -340,16 +355,66 @@ Why not `jina-embeddings-v5-text-nano`? Excellent model, but its EuroBERT archit
 Jina's llama.cpp fork — stock LM Studio can't load it (and the license is CC-BY-NC). See
 `research/lm-studio-model-download-api-and-curated-embedding-reranker-catalog-for-ragx-models-command.md`.
 
+## Checking your setup: `ragx-cli doctor`
+
+`ragx-cli doctor` runs the configured pipeline's providers for real — it embeds a probe string,
+scores a probe pair with the reranker, and checks the index on disk against the config — then
+reports each stage:
+
+```
+✓ config      /corpus/ragx.toml — embeddings=openai/text-embedding-bge-m3 · expansion=openai/qwen3.5-9b · rerank=sentence-transformers/BAAI/bge-reranker-v2-m3
+✗ embeddings  request to http://localhost:1234/v1/embeddings failed after 3 attempts: [Errno 61] Connection refused
+  → ragx does not start this server — launch it at http://localhost:1234/v1 (LM Studio: `lms server start`),
+    or hand the process to ragx with `ragx-cli models --embed-engine llama-server`
+✗ expansion   no server answered at http://localhost:1234/v1/models
+  → turn it off with `ragx-cli config set expansion.enabled false`
+✓ rerank      sentence-transformers/BAAI/bge-reranker-v2-m3 scored a probe pair (-8.14, 4.72)  3.1s
+✓ index       634 files, 1247 chunks, built with 'text-embedding-bge-m3', no drift
+```
+
+Exit codes: `0` healthy, `1` at least one check failed, `2` doctor itself could not run (no
+corpus, unreadable config). Warnings (no index yet, corpus drift, a model the server does not
+list but may JIT-load) do not fail the run. `--json` emits a `ragx.doctor.v1` document with a
+`status`/`detail`/`hint`/`elapsed_ms` entry per check.
+
+**Which servers does ragx start?** All of the local ones:
+
+| engine (`ragx-cli models`) | config | lifecycle |
+| --- | --- | --- |
+| `llama-server` | `provider="llama-server"` (embeddings and/or rerank) | spawned on demand from the configured GGUF and **killed at exit** — ragx owns the process |
+| `lm-studio` | `embeddings.provider="openai"` + a local `base_url` | `lms server start` + `lms load <model>` when nothing answers — LM Studio **keeps running** afterwards (it is an app, not ragx's child) |
+| `sentence-transformers` | `rerank.provider="sentence-transformers"` | in-process, no server |
+
+`index`, `query`, and `doctor` all do this before their first request, so a cold machine needs
+no manual setup. What was started is logged to stderr and shown in doctor's report:
+
+```
+✓ embeddings  started the LM Studio server on port 1234; loaded 'text-embedding-nomic-embed-text-v1.5' into LM Studio — openai/text-embedding-nomic-embed-text-v1.5 answered, dim=768  14.8s
+```
+
+Rules it follows: only a **local** `base_url` is ever touched (a cloud endpoint, including one
+set via `OPENAI_BASE_URL`, is never ragx's to start); an already-running server is left alone,
+and if LM Studio isn't installed but something else answers on that port, ragx just uses it; a
+model that isn't downloaded fails loud naming the models the machine does have. Turn it off per
+section with `ragx-cli config set embeddings.autostart false` (or machine-wide via
+`--global`) — then ragx only ever talks to servers you started.
+
+`ragx-cli models` still only downloads models and writes `ragx.toml`; it never launches
+anything. If a run dies with "connection refused", `doctor` names the stage and the fix.
+
 ## Agent-first conventions
 
 - `--json` emits exactly one JSON document on stdout (versioned schemas: `ragx.query.v1`,
-  `ragx.files.v1`, `ragx.status.v1`, `ragx.eval.v1`, `ragx.inspect.*.v1`); logs go to stderr.
+  `ragx.files.v1`, `ragx.status.v1`, `ragx.doctor.v1`, `ragx.eval.v1`, `ragx.inspect.*.v1`); logs go
+  to stderr.
 - Exit codes: `0` results, `1` success-but-empty, `2` error.
 - Every chunk carries `file`, `line_start/line_end`, `byte_start/byte_end` — agents jump to the
   exact source location and read the full text themselves (JSON chunk text is truncated).
 - `--files-only` aggregates chunk scores per file (sum of top-3) — the mode coding agents use most.
 - `ragx-cli status` includes a `drift` object (`new`/`changed`/`deleted` file counts vs the index) —
   agents check it to decide whether to run `ragx-cli index` before querying.
+- `ragx-cli doctor --json` verifies the providers answer before a batch of queries (`ok: false`
+  plus a per-check `hint` when something is down); exit `1` = a check failed.
 - `ragx-cli query -` reads the query from stdin; `ragx-cli inspect chunk|file|neighbors|communities|community`
   debugs the graph.
 
@@ -528,8 +593,8 @@ below — Enter accepts them all. With piped stdin (agents), `--yes`, or
 | `[communities]` | `resolution=1.0`, `seed=42` — recomputed every index run; changing these never invalidates the index |
 | `[fusion]` | `rrf_k=60`, `per_query_top=20` |
 | `[scoring]` | `alpha_rerank=0.6`, `beta_heat=0.25`, `gamma_vector=0.15` |
-| `[embeddings]` | `provider="openai"`, `base_url="http://localhost:1234/v1"`, prefixes for nomic-style models, `api_key_env=""` |
-| `[expansion]` | optional LLM for multi-query/HyDE; reasoning models supported (4096-token budget); `api_key_env=""` |
+| `[embeddings]` | `provider="openai"`, `base_url="http://localhost:1234/v1"`, prefixes for nomic-style models, `api_key_env=""`, `autostart=true` (start LM Studio + load the model when the URL is local) |
+| `[expansion]` | optional LLM for multi-query/HyDE; reasoning models supported (4096-token budget); `api_key_env=""`, `autostart=true` |
 | `[rerank]` | `BAAI/bge-reranker-v2-m3` via sentence-transformers (`uv tool install 'ragx-cli[rerank]'`) |
 
 ## Features & roadmap

ragx_cli-0.7.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.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragx-cli"
-version = "0.5.1"
+version = "0.7.0"
 description = "Similarity-graph RAG CLI: index a corpus into a chunk-level embedding graph and query it"
 readme = "README.md"
 license = "MIT"
@@ -44,7 +44,7 @@ build-backend = "hatchling.build"
 packages = ["src/ragx"]
 
 [dependency-groups]
-dev = ["pytest>=8", "ruff>=0.6", "respx>=0.21"]
+dev = ["pytest>=8", "ruff>=0.15,<0.16", "respx>=0.21"]
 
 [tool.ruff]
 line-length = 100

{ragx_cli-0.5.1 → ragx_cli-0.7.0}/src/ragx/cli/app.py

@@ -32,12 +32,13 @@ 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")
 
-from ragx.cli import eval_cmd, inspect_cmd, models_cmd, pipeline  # noqa: E402  (needs `app` defined above)
+from ragx.cli import doctor_cmd, eval_cmd, inspect_cmd, models_cmd, pipeline  # noqa: E402  (needs `app` defined above)
 
 pipeline.register(app)
 inspect_cmd.register(app)
 eval_cmd.register(app)
 models_cmd.register(app)
+doctor_cmd.register(app)
 
 
 def _print_version() -> None:
@@ -225,4 +226,5 @@ def config_set(
 
 def main() -> None:
     logging.basicConfig(level=logging.INFO, stream=sys.stderr, format="%(levelname)s: %(message)s")
+    logging.getLogger("httpx").setLevel(logging.WARNING)  # one INFO line per embedding batch
     app()

ragx_cli-0.7.0/src/ragx/cli/doctor_cmd.py

@@ -0,0 +1,62 @@
+"""`doctor`: run the config health checks and render them. Registered by app.py."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from ragx.cli.output import emit_json, fail, migrate_confirm
+from ragx.core.config import Config, require_root
+from ragx.core.doctor import FAIL, OK, SKIP, WARN, DoctorReport, run_doctor, to_doctor_json
+from ragx.core.errors import RagxError
+from ragx.providers.registry import make_embedder, make_generator, make_reranker
+
+MARKS = {OK: "✓", WARN: "!", FAIL: "✗", SKIP: "-"}
+
+
+def register(app: typer.Typer) -> None:
+    app.command()(doctor)
+
+
+def doctor(
+    path: Path | None = typer.Argument(None),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """Check that the configured providers start and answer, and that the index matches.
+
+    Starts whatever ragx itself manages (the llama-server engines), exactly as `index`
+    and `query` would. Exit 0 = healthy, 1 = a check failed, 2 = doctor could not run.
+    """
+    try:
+        root = require_root(path)
+        cfg = Config.load(root, confirm=migrate_confirm())
+    except RagxError as exc:
+        fail(str(exc))
+    report = run_doctor(
+        root,
+        cfg,
+        embedder_factory=make_embedder,
+        generator_factory=make_generator,
+        reranker_factory=lambda c: make_reranker(c, strict=True),
+    )
+    if json_out:
+        emit_json(to_doctor_json(report))
+    else:
+        _render(report)
+    if not report.ok:
+        raise typer.Exit(code=1)
+
+
+def _render(report: DoctorReport) -> None:
+    for check in report.checks:
+        secs = f"  {check.elapsed_ms / 1000:.1f}s" if check.elapsed_ms >= 100 else ""
+        typer.echo(f"{MARKS[check.status]} {check.name:<11} {check.detail}{secs}")
+        if check.hint:
+            typer.echo(f"  → {check.hint}")
+    failed = sum(1 for c in report.checks if c.status == FAIL)
+    warned = sum(1 for c in report.checks if c.status == WARN)
+    if failed or warned:
+        typer.echo(f"\n{failed} failed, {warned} warning(s)")
+    else:
+        typer.echo("\nall checks passed")