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

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

@@ -4,6 +4,40 @@ 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-0.6.0 → 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.6.0 → ragx_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: ragx-cli
-Version: 0.6.0
+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)
@@ -381,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.
 
@@ -569,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.6.0 → 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)
@@ -353,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.
 
@@ -541,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.6.0 → ragx_cli-0.7.0}/pyproject.toml

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

{ragx_cli-0.6.0 → ragx_cli-0.7.0}/src/ragx/cli/pipeline.py

@@ -12,6 +12,7 @@ from ragx.core.config import Config, require_root
 from ragx.core.errors import RagxError
 from ragx.core.indexer import run_index
 from ragx.core.query import QueryOptions, run_query, to_files_json, to_query_json
+from ragx.providers import lmstudio_process
 from ragx.providers.registry import make_embedder, make_generator, make_reranker
 
 
@@ -36,6 +37,7 @@ def index(
     try:
         root = require_root(path)
         cfg = Config.load(root, confirm=migrate_confirm())
+        lmstudio_process.ensure_for_section(cfg, "embeddings")
         stats = run_index(root, cfg, make_embedder(cfg), full=full)
     except RagxError as exc:
         fail(str(exc))
@@ -50,6 +52,16 @@ def index(
         )
 
 
+def _generator(cfg: Config):
+    """Expansion is optional: a backend that won't come up must not sink the query —
+    expand_query degrades to a no-op on any failure."""
+    try:
+        lmstudio_process.ensure_for_section(cfg, "expansion")
+    except RagxError as exc:
+        print(f"warning: query expansion backend unavailable: {exc}", file=sys.stderr)
+    return make_generator(cfg)
+
+
 def query(
     text: str = typer.Argument(..., help="query text, or '-' to read from stdin"),
     top: int | None = typer.Option(None, "--top"),
@@ -67,6 +79,7 @@ def query(
     try:
         root = require_root()
         cfg = Config.load(root, confirm=migrate_confirm())
+        lmstudio_process.ensure_for_section(cfg, "embeddings")
         opts = QueryOptions(
             top=top if top is not None else cfg.get("query.top"),
             files_only=files_only,
@@ -78,7 +91,7 @@ def query(
         )
         out = run_query(
             root, cfg, make_embedder(cfg), text, opts,
-            generator=make_generator(cfg) if opts.expand else None,
+            generator=_generator(cfg) if opts.expand else None,
             reranker=make_reranker(cfg) if opts.rerank else None,
         )
     except RagxError as exc:

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

@@ -75,7 +75,7 @@ EMBEDDINGS: dict[str, EmbeddingChoice] = {
     "balanced": EmbeddingChoice(
         tier="balanced",
         label="BGE-M3",
-        ref="https://huggingface.co/gaianet/bge-m3-GGUF",
+        ref="https://huggingface.co/gpustack/bge-m3-GGUF@Q8_0",
         repo_fragment="bge-m3",
         doc_prefix="",
         query_prefix="",
@@ -84,7 +84,7 @@ EMBEDDINGS: dict[str, EmbeddingChoice] = {
         context="8K",
         download_mb=600,
         notes="ragx's benchmarked production model",
-        gguf_ref="https://huggingface.co/gaianet/bge-m3-GGUF",
+        gguf_ref="https://huggingface.co/gpustack/bge-m3-GGUF@Q8_0",
         gguf_fragment="bge-m3",
     ),
     "best": EmbeddingChoice(

{ragx_cli-0.6.0 → ragx_cli-0.7.0}/src/ragx/core/config.py

@@ -5,6 +5,7 @@ The rc overrides corpus values — with a warning."""
 from __future__ import annotations
 
 import logging
+import os
 import tomllib
 from collections.abc import Callable
 from pathlib import Path
@@ -46,6 +47,7 @@ DEFAULTS: dict[str, dict[str, Any]] = {
         "query_prefix": "search_query: ",
         "batch_size": 32,
         "api_key_env": "",  # NAME of an env var holding the API key; empty = no auth header
+        "autostart": True,  # provider="openai" + local base_url: start LM Studio and load the model
         "gguf": "",  # llama-server only: path to the embedding GGUF (LM Studio dir works)
         "server_bin": "llama-server",  # llama-server only: binary name or path
     },
@@ -57,6 +59,7 @@ DEFAULTS: dict[str, dict[str, Any]] = {
         "variants": 3,
         "hyde": True,
         "api_key_env": "",
+        "autostart": True,  # see embeddings.autostart
     },
     "rerank": {
         "enabled": True,
@@ -143,6 +146,20 @@ def _coerce(section: str, key: str, value: Any) -> Any:
     return value
 
 
+DEFAULT_OPENAI_BASE_URL = DEFAULTS["embeddings"]["base_url"]  # the LM Studio default
+
+
+def effective_base_url(cfg: "Config", section: str) -> str:
+    """The URL a provider section actually talks to: `<section>.base_url`, unless it is
+    still the built-in default and OPENAI_BASE_URL is set — an explicit `config set`
+    always wins. Providers and the LM Studio autostart must agree on this."""
+    base_url = cfg.get(f"{section}.base_url")
+    env_url = os.environ.get("OPENAI_BASE_URL")
+    if env_url and base_url == DEFAULT_OPENAI_BASE_URL:
+        return env_url.rstrip("/")
+    return base_url
+
+
 def load_rc(rc: Path | None = None) -> dict[str, dict[str, Any]]:
     """Parse ~/.ragxrc. Only provider sections with known keys are allowed — fails loud."""
     path = rc if rc is not None else rc_path()