ragx-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/.gitignore

@@ -7,3 +7,5 @@ dist/
 .ragx/
 uv.lock
 .claude/worktrees/
+.lab/
+run.log

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/CLAUDE.md

@@ -23,6 +23,11 @@ API contracts for every core module. Deferred feature specs live in `docs/`.
   `http://localhost:1234/v1`. `provider="ollama"` auto-switches to `:11434/v1`.
   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.
+- Machine-level provider settings live in `~/.ragxrc` (TOML; ONLY the embeddings/
+  expansion/rerank sections, unknown keys fail loud). Precedence: DEFAULTS < corpus
+  config.toml < ~/.ragxrc — the rc OVERRIDES corpus values and logs a stderr warning
+  per overridden key. Write via `ragx-cli config set --global <key> <value>`.
+  `Config.save` never bakes rc values into the corpus file.
 - Reranker is always local: sentence-transformers CrossEncoder `BAAI/bge-reranker-v2-m3`
   (optional extra `ragx-cli[rerank]`). LM Studio has NO /v1/rerank endpoint — verified; don't try.
 
@@ -31,7 +36,7 @@ API contracts for every core module. Deferred feature specs live in `docs/`.
 ```
 src/ragx/
   core/            # all logic lives here, CLI-independent
-    config.py      #   .ragx/config.toml load/save, DEFAULTS dict, find_root/require_root
+    config.py      #   .ragx/config.toml + ~/.ragxrc (provider sections; rc wins, warns), DEFAULTS, find_root
     models.py      #   Chunk, ChunkDraft, FileRecord, Edge, ScoredChunk, QueryOutput
     store.py       #   SQLite: files/chunks/edges/meta; replace_edges normalizes src<dst
     vectors.py     #   hnswlib wrapper; soft-delete via JSON sidecar; get_vectors for graph
@@ -82,9 +87,8 @@ unreachable by vector search or rerank-alone, surfaced only via a hop-1 edge the
 
 ## Gotchas
 
-- Ornith (`mlx-community/Ornith-1.0-35B-3bit`, Albert's required expansion LLM) is a
-  *reasoning* model: answers land in `content` only after thinking; expansion uses
-  max_tokens=4096 and takes ~40 s/call. Don't lower it.
+- 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
   mismatch; full `ragx-cli index` rebuilds.
 - Chunk ids are SQLite AUTOINCREMENT rowids AND hnswlib labels — never reused after delete.
@@ -92,8 +96,8 @@ unreachable by vector search or rerank-alone, surfaced only via a hop-1 edge the
 - `Config.set` rejects keys not in `DEFAULTS` — add new config keys to DEFAULTS first.
 - Tests must not hit the network; one provider test self-skips when sentence-transformers
   is installed. Pyright import errors in editors = interpreter not set to `.venv`.
-- When running ragx against the wiki corpus: `cd` there, then
-  `uv run --project /Users/albert/projects/alber70g/ragx ragx-cli …` — and NEVER `git add`/commit
+- When running ragx-cli against the wiki corpus: `cd` there, then
+  `uv run --project /Users/albert/projects/alber70g/ragx-cli ragx-cli …` — and NEVER `git add`/commit
   from that directory (it's Albert's personal notes repo; `.ragx/` is gitignored there).
 
 ## What's next / deferred
@@ -110,3 +114,5 @@ unreachable by vector search or rerank-alone, surfaced only via a hop-1 edge the
 `uv sync --group dev --extra rerank` · `uv run pytest -q` (126 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)
+must get their representation in README.md in the same change.

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/CONTRACTS-PHASE23.md

@@ -1,4 +1,4 @@
-# ragx module contracts — Phase 2–3 build
+# ragx-cli module contracts — Phase 2–3 build
 
 Same ground rules as CONTRACTS.md (read its "Global rules" and "Report protocol" — they apply
 verbatim). Own ONLY your listed files; never modify shared/core files or other modules' files.
@@ -131,7 +131,7 @@ def evaluate(queries: list[dict], configs: list[tuple[str, QueryOptions]], query
 
 # eval_cmd.py
 def register(app: typer.Typer) -> None: ...
-# ragx eval QUERIES_FILE [--json] [--top N] [--configs csv]
+# ragx-cli eval QUERIES_FILE [--json] [--top N] [--configs csv]
 # built-in configs: baseline (expand/graph/rerank all off), graph (only graph on),
 #                   full (all on). Default: run all three.
 # Constructs QueryOptions accordingly and query_fn from run_query + make_embedder(cfg) —
@@ -151,10 +151,10 @@ a monkeypatched evaluate/query_fn (no embeddings, no network).
 
 ```python
 def register(app: typer.Typer) -> None:   # app.add_typer(inspect_app, name="inspect")
-# ragx inspect chunk ID [--json]      -> chunk text, file, line/byte range + its edges
+# ragx-cli inspect chunk ID [--json]      -> chunk text, file, line/byte range + its edges
 #                                        (neighbor id, weight, neighbor's file path)
-# ragx inspect file PATH [--json]     -> file record + its chunks (id, line range, first 80 chars)
-# ragx inspect neighbors ID [--json]  -> store.neighbors(ID) enriched with each neighbor's file/lines
+# ragx-cli inspect file PATH [--json]     -> file record + its chunks (id, line range, first 80 chars)
+# ragx-cli inspect neighbors ID [--json]  -> store.neighbors(ID) enriched with each neighbor's file/lines
 ```
 
 All read-only over Store (find root via require_root; no embeddings, no vectors file needed).

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/CONTRACTS.md

@@ -1,4 +1,4 @@
-# ragx module contracts (Phase 0–1 build)
+# ragx-cli module contracts (Phase 0–1 build)
 
 Ground truth for the module-parallel build. Each module owns exactly the files listed for it.
 **Do not create or edit files outside your module** — shared types live in `core/models.py`,
@@ -93,7 +93,7 @@ class OpenAICompatGenerator:  # implements providers.base.Generator
     # returns choices[0].message.content
 
 # st_reranker.py — lazy `import sentence_transformers` inside __init__;
-# ImportError -> RagxError("... install with: uv pip install 'ragx[rerank]'")
+# ImportError -> RagxError("... install with: uv tool install ragx-cli --with ragx-cli[rerank]")
 class STReranker:             # implements providers.base.Reranker
     def __init__(self, model: str): ...
     def score(self, query: str, texts: Sequence[str]) -> list[float]: ...  # CrossEncoder.predict
@@ -205,11 +205,11 @@ def fail(msg: str, code: int = 2) -> NoReturn: ...
 
 # app.py
 app = typer.Typer(...)
-# ragx init [path]      -> write_default_config at path (default cwd); error (exit 2) if .ragx exists;
+# ragx-cli init [path]      -> write_default_config at path (default cwd); error (exit 2) if .ragx-cli exists;
 #                          prints created config path
-# ragx status [--json]  -> root path, embedding model/provider, counts (files/chunks/edges) read via
+# ragx-cli status [--json]  -> root path, embedding model/provider, counts (files/chunks/edges) read via
 #                          Store if index.db exists else zeros, schema "ragx.status.v1" in JSON mode
-# ragx config get KEY / ragx config set KEY VALUE  -> Config.get / Config.set + save
+# ragx-cli config get KEY / ragx-cli config set KEY VALUE  -> Config.get / Config.set + save
 def main() -> None: ...   # entry point declared in pyproject [project.scripts]
 ```
 

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragx-cli
-Version: 0.1.0
+Version: 0.2.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
@@ -45,7 +45,7 @@ JSON schemas, deterministic exit codes, byte-exact source locations, and an `--e
 that can justify every result via the exact graph path that produced it.
 
 ```bash
-uv tool install ragx-cli       # or run one-off without installing: uvx ragx-cli ...
+uv tool install ragx-cli --with ragx-cli[rerank]  # install and use `ragx-cli`
 ragx-cli init                  # create .ragx/ with config.toml next to your corpus
 ragx-cli index                 # chunk -> embed -> HNSW + kNN similarity graph
 ragx-cli query "why did we switch build tools?" --json --files-only
@@ -63,11 +63,13 @@ uses a local sentence-transformers cross-encoder (`ragx-cli[rerank]` extra). Eve
     - [Indexing (LLM-free)](#indexing-llm-free)
     - [Querying](#querying)
   - [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)
   - [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)
+    - [Machine-level settings: `~/.ragxrc`](#machine-level-settings-ragxrc)
   - [Configuration](#configuration)
-  - [Features & roadmap](#features--roadmap)
+  - [Features \& roadmap](#features--roadmap)
 
 
 ## How it works
@@ -178,6 +180,73 @@ sweep over decay/floor/weights plateaued below baseline MRR, so this is a proper
 similarity-only edges, not a tuning miss. Conclusion baked into the defaults: **graph and
 rerank ship together**. Use `--no-graph --no-rerank` as the explicit fast mode.
 
+The parameter study below explains the mechanism behind this caveat — and shows that once the
+scoring weights stop putting heat into the final score, the graph win gets much bigger.
+
+### Parameter study: what each knob actually does (2026-07)
+
+A follow-up study swept every traversal, scoring, and graph-build parameter to map sensitivity
+and find better settings. Setup: a scoped subset of the same wiki (`clients/` + `workstreams/`:
+383 files → 720 chunks → 2,848 edges) with a fresh 26-query EN+NL label set.
+
+**Process.** Sweeping through real `eval` runs costs ~9 minutes each, so the study used an
+offline harness (`.lab/harness.py`): one retrieval pass per query plus a text-keyed cross-encoder
+score cache lets any traversal × scoring × edge-filter combination be re-evaluated in seconds —
+the combination step is deterministic post-processing, and rerank scores depend only on
+(query, chunk text). The harness was validated **digit-exact** against the real pipeline before
+use, ~125 configurations were measured in staged rounds (scoring simplex → refinement →
+traversal one-factor-at-a-time → interaction grid → edge-filter simulations), the winning config
+was re-verified with a real `eval` run (again digit-exact), and finally replicated on an
+independently rebuilt index.
+
+**Result** — same-index comparisons, `rerank` config (no expansion) unless noted:
+
+| config | MRR | recall@5 | recall@10 |
+|---|---:|---:|---:|
+| defaults (`hops=2`, α/β/γ = .6/.25/.15) | 0.665 | 0.885 | 0.923 |
+| **tuned (`hops=3`, α/β/γ = .9/0/.1)** | **0.755** | 0.885 | **0.962** |
+
+The +13.7% MRR delta replicated as +14.5% on an independently rebuilt index (absolute numbers
+differ per build — see the measurement caveat below).
+
+Apply the tuned settings to a corpus with:
+
+```bash
+ragx-cli config set traversal.hops 3
+ragx-cli config set scoring.alpha_rerank 0.9
+ragx-cli config set scoring.beta_heat 0.0
+ragx-cli config set scoring.gamma_vector 0.1
+```
+
+**Discoveries**, in decreasing order of impact:
+
+- **α (rerank weight) is the dominant knob.** MRR rises monotonically from α=.6 to a plateau at
+  α≈.85–.9 (+9% relative), with recall flat across the whole range. Heat belongs at **β=0**:
+  once the cross-encoder is trusted, heat in the final score only adds near-duplicate noise —
+  which is exactly why the earlier graph-only sweeps plateaued.
+- **But never α=1.0.** With β=γ=0 the pre-rerank shortlist selector degenerates (it renormalizes
+  β:γ, so every pre-score becomes 0) and MRR collapses to 0.32. Vector + heat pick *which* 100
+  candidates the cross-encoder sees at all — they are load-bearing for shortlist selection even
+  at near-zero final weight. Keep γ > 0.
+- **`hops=3` is the second win, but only after fixing the scoring.** Under default weights,
+  traversal depth is completely inert (heat dilution cancels the candidate gains); under
+  rerank-heavy weights it adds both MRR and recall@10. **`hops=4` degrades**: ~570 candidates
+  overwhelm the fixed rerank shortlist (`RERANK_CAP=100`) and good candidates get evicted before
+  the cross-encoder ever sees them — the cap, not the graph, becomes the binding constraint.
+- **Graph = recall channel, cross-encoder = precision channel.** At identical tuned scoring,
+  removing the graph keeps MRR (0.71) but drops recall@10 by 7.7 points. The graph's job is to
+  put reachable targets in front of the reranker; the reranker's job is to rank them.
+- **Everything else is inert or already optimal**: `decay` (.3–.7), `query_floor` (.2–.5),
+  `max_frontier` (50–300), and `min_edge_sim` (up to .7) don't move metrics; `k=8` is bracketed
+  optimal from both sides (k=4/6 lose recall, a real k=12 rebuild was no better).
+- **LLM expansion buys recall, not ranking.** The full pipeline at default params reached the
+  same recall@10 that `hops=3` provides for free, at ~40 s/query for a local reasoning model.
+  On tuned params expansion still stacked (+.03 MRR) — worth it only when latency doesn't matter.
+- **Measurement caveat: index rebuilds are not reproducible across embedding-server sessions.**
+  Rebuilding is deterministic within a session, but embeddings drift between LM Studio sessions
+  (~.04 MRR at identical params). Compare configs on the same build only; the tuned-vs-default
+  delta replicated across two independent builds (+13.7% / +14.5% MRR).
+
 ---
 
 ## Agent-first conventions
@@ -264,9 +333,28 @@ Mixed setups are normal — e.g. local Ollama embeddings + online expansion via
 download is unwanted. **Note:** changing the embedding model invalidates the index — ragx-cli
 detects the mismatch and asks you to run a full `ragx-cli index`.
 
+### Machine-level settings: `~/.ragxrc`
+
+Provider settings that belong to the machine rather than the corpus — which embedding
+model, which LLM, which base URL — can live in `~/.ragxrc` (TOML, same shape as
+`config.toml`, restricted to the `[embeddings]`, `[expansion]`, and `[rerank]` sections):
+
+```bash
+ragx-cli config set --global embeddings.model text-embedding-nomic-embed-text-v1.5
+ragx-cli config set --global expansion.model llama3.1
+```
+
+Precedence: built-in defaults < corpus `.ragx/config.toml` < `~/.ragxrc`. The rc
+**overrides** corpus values, and every command warns on stderr when it does, so a
+corpus config never loses silently. Set corpus-specific values without `--global`
+as usual. Other sections (chunking, graph, …) are corpus-level and rejected from
+the rc. The index-invalidation note above applies equally when the rc changes the
+effective embedding model.
+
 ## Configuration
 
-`.ragx/config.toml`, managed via `ragx-cli config get|set`. Key defaults:
+`.ragx/config.toml`, managed via `ragx-cli config get|set` (add `--global` to write
+provider settings to `~/.ragxrc` instead — see above). Key defaults:
 
 | section | defaults |
 |---|---|

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/README.md

@@ -19,7 +19,7 @@ JSON schemas, deterministic exit codes, byte-exact source locations, and an `--e
 that can justify every result via the exact graph path that produced it.
 
 ```bash
-uv tool install ragx-cli       # or run one-off without installing: uvx ragx-cli ...
+uv tool install ragx-cli --with ragx-cli[rerank]  # install and use `ragx-cli`
 ragx-cli init                  # create .ragx/ with config.toml next to your corpus
 ragx-cli index                 # chunk -> embed -> HNSW + kNN similarity graph
 ragx-cli query "why did we switch build tools?" --json --files-only
@@ -37,11 +37,13 @@ uses a local sentence-transformers cross-encoder (`ragx-cli[rerank]` extra). Eve
     - [Indexing (LLM-free)](#indexing-llm-free)
     - [Querying](#querying)
   - [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)
   - [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)
+    - [Machine-level settings: `~/.ragxrc`](#machine-level-settings-ragxrc)
   - [Configuration](#configuration)
-  - [Features & roadmap](#features--roadmap)
+  - [Features \& roadmap](#features--roadmap)
 
 
 ## How it works
@@ -152,6 +154,73 @@ sweep over decay/floor/weights plateaued below baseline MRR, so this is a proper
 similarity-only edges, not a tuning miss. Conclusion baked into the defaults: **graph and
 rerank ship together**. Use `--no-graph --no-rerank` as the explicit fast mode.
 
+The parameter study below explains the mechanism behind this caveat — and shows that once the
+scoring weights stop putting heat into the final score, the graph win gets much bigger.
+
+### Parameter study: what each knob actually does (2026-07)
+
+A follow-up study swept every traversal, scoring, and graph-build parameter to map sensitivity
+and find better settings. Setup: a scoped subset of the same wiki (`clients/` + `workstreams/`:
+383 files → 720 chunks → 2,848 edges) with a fresh 26-query EN+NL label set.
+
+**Process.** Sweeping through real `eval` runs costs ~9 minutes each, so the study used an
+offline harness (`.lab/harness.py`): one retrieval pass per query plus a text-keyed cross-encoder
+score cache lets any traversal × scoring × edge-filter combination be re-evaluated in seconds —
+the combination step is deterministic post-processing, and rerank scores depend only on
+(query, chunk text). The harness was validated **digit-exact** against the real pipeline before
+use, ~125 configurations were measured in staged rounds (scoring simplex → refinement →
+traversal one-factor-at-a-time → interaction grid → edge-filter simulations), the winning config
+was re-verified with a real `eval` run (again digit-exact), and finally replicated on an
+independently rebuilt index.
+
+**Result** — same-index comparisons, `rerank` config (no expansion) unless noted:
+
+| config | MRR | recall@5 | recall@10 |
+|---|---:|---:|---:|
+| defaults (`hops=2`, α/β/γ = .6/.25/.15) | 0.665 | 0.885 | 0.923 |
+| **tuned (`hops=3`, α/β/γ = .9/0/.1)** | **0.755** | 0.885 | **0.962** |
+
+The +13.7% MRR delta replicated as +14.5% on an independently rebuilt index (absolute numbers
+differ per build — see the measurement caveat below).
+
+Apply the tuned settings to a corpus with:
+
+```bash
+ragx-cli config set traversal.hops 3
+ragx-cli config set scoring.alpha_rerank 0.9
+ragx-cli config set scoring.beta_heat 0.0
+ragx-cli config set scoring.gamma_vector 0.1
+```
+
+**Discoveries**, in decreasing order of impact:
+
+- **α (rerank weight) is the dominant knob.** MRR rises monotonically from α=.6 to a plateau at
+  α≈.85–.9 (+9% relative), with recall flat across the whole range. Heat belongs at **β=0**:
+  once the cross-encoder is trusted, heat in the final score only adds near-duplicate noise —
+  which is exactly why the earlier graph-only sweeps plateaued.
+- **But never α=1.0.** With β=γ=0 the pre-rerank shortlist selector degenerates (it renormalizes
+  β:γ, so every pre-score becomes 0) and MRR collapses to 0.32. Vector + heat pick *which* 100
+  candidates the cross-encoder sees at all — they are load-bearing for shortlist selection even
+  at near-zero final weight. Keep γ > 0.
+- **`hops=3` is the second win, but only after fixing the scoring.** Under default weights,
+  traversal depth is completely inert (heat dilution cancels the candidate gains); under
+  rerank-heavy weights it adds both MRR and recall@10. **`hops=4` degrades**: ~570 candidates
+  overwhelm the fixed rerank shortlist (`RERANK_CAP=100`) and good candidates get evicted before
+  the cross-encoder ever sees them — the cap, not the graph, becomes the binding constraint.
+- **Graph = recall channel, cross-encoder = precision channel.** At identical tuned scoring,
+  removing the graph keeps MRR (0.71) but drops recall@10 by 7.7 points. The graph's job is to
+  put reachable targets in front of the reranker; the reranker's job is to rank them.
+- **Everything else is inert or already optimal**: `decay` (.3–.7), `query_floor` (.2–.5),
+  `max_frontier` (50–300), and `min_edge_sim` (up to .7) don't move metrics; `k=8` is bracketed
+  optimal from both sides (k=4/6 lose recall, a real k=12 rebuild was no better).
+- **LLM expansion buys recall, not ranking.** The full pipeline at default params reached the
+  same recall@10 that `hops=3` provides for free, at ~40 s/query for a local reasoning model.
+  On tuned params expansion still stacked (+.03 MRR) — worth it only when latency doesn't matter.
+- **Measurement caveat: index rebuilds are not reproducible across embedding-server sessions.**
+  Rebuilding is deterministic within a session, but embeddings drift between LM Studio sessions
+  (~.04 MRR at identical params). Compare configs on the same build only; the tuned-vs-default
+  delta replicated across two independent builds (+13.7% / +14.5% MRR).
+
 ---
 
 ## Agent-first conventions
@@ -238,9 +307,28 @@ Mixed setups are normal — e.g. local Ollama embeddings + online expansion via
 download is unwanted. **Note:** changing the embedding model invalidates the index — ragx-cli
 detects the mismatch and asks you to run a full `ragx-cli index`.
 
+### Machine-level settings: `~/.ragxrc`
+
+Provider settings that belong to the machine rather than the corpus — which embedding
+model, which LLM, which base URL — can live in `~/.ragxrc` (TOML, same shape as
+`config.toml`, restricted to the `[embeddings]`, `[expansion]`, and `[rerank]` sections):
+
+```bash
+ragx-cli config set --global embeddings.model text-embedding-nomic-embed-text-v1.5
+ragx-cli config set --global expansion.model llama3.1
+```
+
+Precedence: built-in defaults < corpus `.ragx/config.toml` < `~/.ragxrc`. The rc
+**overrides** corpus values, and every command warns on stderr when it does, so a
+corpus config never loses silently. Set corpus-specific values without `--global`
+as usual. Other sections (chunking, graph, …) are corpus-level and rejected from
+the rc. The index-invalidation note above applies equally when the rc changes the
+effective embedding model.
+
 ## Configuration
 
-`.ragx/config.toml`, managed via `ragx-cli config get|set`. Key defaults:
+`.ragx/config.toml`, managed via `ragx-cli config get|set` (add `--global` to write
+provider settings to `~/.ragxrc` instead — see above). Key defaults:
 
 | section | defaults |
 |---|---|

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/docs/feature-temporal-weighting.md

@@ -6,7 +6,7 @@ exists, so its effect on recall/MRR is measured against a stable baseline before
 ## Decisions
 
 1. **Opt-in only.** Temporal signals never influence ranking by default. No δ-term in the default
-   scoring formula. All behavior is activated by explicit `ragx query` flags.
+   scoring formula. All behavior is activated by explicit `ragx-cli query` flags.
 2. **Capabilities** (all three):
    - **Hard filters:** `--since <date>` / `--until <date>` constrain candidates by document date.
    - **Recency bias, directional:** a decay boost that is *configurable in direction* —
@@ -30,7 +30,7 @@ exists, so its effect on recall/MRR is measured against a stable baseline before
 
 - Schema: `files.doc_date` (ISO date, nullable) + `files.date_source` → SQLite `user_version = 2`
   migration. Backfill needs only a metadata pass (re-run date extraction per file) — **no
-  re-embedding required**; add e.g. `ragx index --refresh-dates`.
+  re-embedding required**; add e.g. `ragx-cli index --refresh-dates`.
 - Chunks inherit their file's date (chunk-level dates from in-text mentions were considered and
   parked — noisy, and most of the corpus is single-date documents).
 - Filters apply before traversal (constrain seeds and admitted neighbors); bias applies after

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragx-cli"
-version = "0.1.0"
+version = "0.2.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.1.0 → ragx_cli-0.2.0}/ragx-cli-plan.md

@@ -53,13 +53,13 @@ Rationale: the entire retrieval ecosystem (FAISS/HNSW, sentence-transformers cro
 ## 3. CLI surface
 
 ```
-ragx init [path]                  # create .ragx/, write default config.toml
-ragx index [path] [--changed]     # chunk, embed, build/update kNN graph
-ragx query "..." [--json] [--top N] [--no-expand] [--no-graph] [--no-rerank]
+ragx-cli init [path]                  # create .ragx/, write default config.toml
+ragx-cli index [path] [--changed]     # chunk, embed, build/update kNN graph
+ragx-cli query "..." [--json] [--top N] [--no-expand] [--no-graph] [--no-rerank]
               [--files-only] [--hops H] [--explain]
-ragx inspect chunk <id> | file <path> | neighbors <id>   # debug the graph
-ragx status                       # index freshness, counts, config summary
-ragx config get|set <key> [value]
+ragx-cli inspect chunk <id> | file <path> | neighbors <id>   # debug the graph
+ragx-cli status                       # index freshness, counts, config summary
+ragx-cli config get|set <key> [value]
 ```
 
 Conventions for agent use: `--json` emits a single JSON document on stdout (schema versioned, `"schema": "ragx.query.v1"`); logs go to stderr; exit code 0 = success with results, 1 = success but empty, 2 = error. `query` also accepts the query on stdin when the argument is `-`.
@@ -74,7 +74,7 @@ Conventions for agent use: `--json` emits a single JSON document on stdout (sche
 2. **Chunking.** Structure-aware where cheap: split Markdown on headings, code on function boundaries (tree-sitter optional, regex fallback), plain text by recursive character splitting. Defaults: ~800 tokens, 15% overlap. Every chunk records `file, byte_start, byte_end, line_start, line_end` so agents can jump to exact locations.
 3. **Embedding.** Batch through the configured provider, applying document prefixes if the model requires them. Store vectors in HNSW; store chunk metadata in SQLite.
 4. **Graph construction.** For every chunk, query HNSW for top-`k` neighbors (default k=8) above a similarity floor (default cosine ≥ 0.55, configurable). Write undirected weighted edges to SQLite (`edges(src, dst, weight)`), deduplicated. This is the entire "graph build" — one ANN pass over data already in memory.
-5. **Incremental updates.** New/changed chunks: embed, insert, compute their edges, and recompute edges only for chunks that appear in the new chunks' neighbor lists. Deleted files: remove chunks, vectors (HNSW soft-delete + periodic `ragx index --compact`), and incident edges.
+5. **Incremental updates.** New/changed chunks: embed, insert, compute their edges, and recompute edges only for chunks that appear in the new chunks' neighbor lists. Deleted files: remove chunks, vectors (HNSW soft-delete + periodic `ragx-cli index --compact`), and incident edges.
 
 ### 4.2 Query
 
@@ -96,11 +96,11 @@ Stages are individually skippable via flags so agents can trade quality for late
 
 **Phase 2 — Similarity graph (1–2 days).** Edge construction during indexing, `inspect` commands, heat-propagation traversal in `query`, `--explain` output, incremental edge maintenance. Evaluate: recall@10 with graph on vs. off on a small labeled query set (~20 queries is enough to steer).
 
-**Phase 3 — Expansion + rerank (1–2 days).** Multi-query/HyDE expansion stage, RRF fusion, cross-encoder reranker, combined scoring, `--no-*` flags. Add a tiny built-in eval harness: `ragx eval queries.jsonl` reporting recall@k / MRR per pipeline configuration, so parameter tuning (k, decay, floors, α/β/γ) is measurable instead of vibes.
+**Phase 3 — Expansion + rerank (1–2 days).** Multi-query/HyDE expansion stage, RRF fusion, cross-encoder reranker, combined scoring, `--no-*` flags. Add a tiny built-in eval harness: `ragx-cli eval queries.jsonl` reporting recall@k / MRR per pipeline configuration, so parameter tuning (k, decay, floors, α/β/γ) is measurable instead of vibes.
 
 **Phase 4 — Scale + communities (optional, 2–3 days).** Leiden community detection over the edge list; per-community extractive labels (top-TF-IDF terms — still no LLM required) or optional LLM summaries; `query --global` mode that routes through communities for corpus-level questions. Performance work: batch/parallel embedding, HNSW `ef` tuning, compaction.
 
-**Phase 5 — MCP (later, deliberately deferred).** Because all query logic lives in a `ragx.core` library layer with the CLI as a thin shell, the MCP server is a second thin shell: `ragx serve --mcp` exposing `query`, `inspect`, `status` as tools over stdio. No refactor needed if the core/CLI split is respected from Phase 0 — that split is the one architectural rule to enforce early.
+**Phase 5 — MCP (later, deliberately deferred).** Because all query logic lives in a `ragx.core` library layer with the CLI as a thin shell, the MCP server is a second thin shell: `ragx-cli serve --mcp` exposing `query`, `inspect`, `status` as tools over stdio. No refactor needed if the core/CLI split is respected from Phase 0 — that split is the one architectural rule to enforce early.
 
 ---
 
@@ -124,15 +124,15 @@ Stages are individually skippable via flags so agents can trade quality for late
 1. **Hub chunks** (boilerplate, headers) attract many edges and dominate traversal. Mitigate: max-not-sum heat aggregation, per-node degree cap (drop edges beyond top-k both directions), optional stopword-density filter at chunking time.
 2. **Similarity ≠ relevance.** Graph neighbors of a relevant chunk can be topically adjacent but useless. The query-floor filter during traversal and the cross-encoder rerank are the two guards; the eval harness (Phase 3) verifies they're working.
 3. **HNSW deletes** degrade the index over time. Soft-delete + `--compact` rebuild; acceptable for corpora that change incrementally.
-4. **Embedding model changes** invalidate everything. Store model name + dimension in the manifest; refuse to mix, offer `ragx index --rebuild`.
+4. **Embedding model changes** invalidate everything. Store model name + dimension in the manifest; refuse to mix, offer `ragx-cli index --rebuild`.
 5. **Agent misuse of long output.** Default `--top 8`, chunk text truncated to a configurable max in JSON output with `byte_start/byte_end` so agents fetch full text from the file themselves.
 
 ---
 
 ## 8. Definition of done (pre-MCP)
 
-- `uvx ragx init && ragx index && ragx query "..." --json --files-only` works on a fresh repo with only Ollama running.
-- Incremental `ragx index --changed` after editing one file touches only affected chunks/edges.
+- `uvx ragx-cli init && ragx-cli index && ragx-cli query "..." --json --files-only` works on a fresh repo with only Ollama running.
+- Incremental `ragx-cli index --changed` after editing one file touches only affected chunks/edges.
 - Eval harness shows graph expansion improving recall@10 over the Phase 1 baseline on the reference query set, with rerank recovering precision.
 - `--explain` can justify every returned chunk via seed → edge path → scores.
 

ragx_cli-0.2.0/src/ragx/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/src/ragx/cli/app.py

@@ -1,4 +1,4 @@
-"""ragx CLI shell: init, status, config. index/query are wired in a later pass."""
+"""ragx-cli CLI shell: init, status, config. index/query are wired in a later pass."""
 
 from __future__ import annotations
 
@@ -9,7 +9,15 @@ from pathlib import Path
 import typer
 
 from ragx.cli.output import emit_json, fail
-from ragx.core.config import Config, RAGX_DIR, db_path, require_root, write_default_config
+from ragx.core.config import (
+    Config,
+    RAGX_DIR,
+    db_path,
+    rc_path,
+    require_root,
+    write_default_config,
+    write_rc_value,
+)
 from ragx.core.errors import RagxError
 
 app = typer.Typer(add_completion=False, no_args_is_help=True)
@@ -89,7 +97,18 @@ def config_get(key: str) -> None:
 
 
 @config_app.command("set")
-def config_set(key: str, value: str) -> None:
+def config_set(
+    key: str,
+    value: str,
+    global_: bool = typer.Option(False, "--global", help="write to ~/.ragxrc (provider settings only)"),
+) -> None:
+    if global_:
+        try:
+            coerced = write_rc_value(key, value)
+        except RagxError as exc:
+            fail(str(exc))
+        typer.echo(f"{key} = {coerced} ({rc_path()})")
+        return
     root = _require_root()
     cfg = Config.load(root)
     try:
@@ -97,7 +116,8 @@ def config_set(key: str, value: str) -> None:
     except RagxError as exc:
         fail(str(exc))
     cfg.save(root)
-    typer.echo(f"{key} = {cfg.get(key)}")
+    # reload so the echoed value is the effective one (an rc override warns and wins)
+    typer.echo(f"{key} = {Config.load(root).get(key)}")
 
 
 def main() -> None:

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/src/ragx/cli/eval_cmd.py

@@ -1,4 +1,4 @@
-"""`ragx eval` command. Registered onto the main app by app.py (integration-owned)."""
+"""`ragx-cli eval` command. Registered onto the main app by app.py (integration-owned)."""
 
 from __future__ import annotations
 

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/src/ragx/cli/inspect_cmd.py

@@ -1,4 +1,4 @@
-"""ragx inspect: read-only introspection into the store (chunks, files, neighbors).
+"""ragx-cli inspect: read-only introspection into the store (chunks, files, neighbors).
 
 No embeddings or vector index needed — everything here reads Store directly.
 """

ragx_cli-0.2.0/src/ragx/core/config.py

@@ -0,0 +1,200 @@
+"""Config: .ragx/config.toml per corpus, plus ~/.ragxrc for machine-level provider
+settings (embeddings/expansion/rerank). The rc overrides corpus values — with a warning."""
+
+from __future__ import annotations
+
+import logging
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import tomli_w
+
+from ragx.core.errors import NotInitializedError, RagxError
+
+RAGX_DIR = ".ragx"
+PROVIDER_SECTIONS = ("embeddings", "expansion", "rerank")
+
+log = logging.getLogger("ragx.config")
+
+
+def rc_path() -> Path:
+    return Path.home() / ".ragxrc"
+
+DEFAULTS: dict[str, dict[str, Any]] = {
+    "corpus": {"include": ["**/*"], "exclude": [], "respect_gitignore": True},
+    "chunking": {"size_tokens": 800, "overlap": 0.15},
+    "graph": {"k": 8, "min_edge_sim": 0.55},
+    "traversal": {"hops": 2, "decay": 0.5, "query_floor": 0.35, "max_frontier": 150},
+    "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",
+        "model": "text-embedding-nomic-embed-text-v1.5@q4_k_m",
+        "doc_prefix": "search_document: ",
+        "query_prefix": "search_query: ",
+        "batch_size": 32,
+        "api_key_env": "",  # NAME of an env var holding the API key; empty = no auth header
+    },
+    "expansion": {
+        "enabled": True,
+        "provider": "openai",
+        "base_url": "http://localhost:1234/v1",
+        "model": "qwen3.5-9b",
+        "variants": 3,
+        "hyde": True,
+        "api_key_env": "",
+    },
+    "rerank": {"enabled": True, "provider": "sentence-transformers", "model": "BAAI/bge-reranker-v2-m3"},
+    "query": {"top": 8, "max_chunk_chars": 1200},
+}
+
+
+def find_root(start: Path | None = None) -> Path | None:
+    """Walk up from `start` (default cwd) looking for a .ragx/ directory."""
+    cur = (start or Path.cwd()).resolve()
+    for p in [cur, *cur.parents]:
+        if (p / RAGX_DIR).is_dir():
+            return p
+    return None
+
+
+def require_root(start: Path | None = None) -> Path:
+    root = find_root(start)
+    if root is None:
+        raise NotInitializedError("no .ragx/ found — run `ragx-cli init` first")
+    return root
+
+
+def config_path(root: Path) -> Path:
+    return root / RAGX_DIR / "config.toml"
+
+
+def db_path(root: Path) -> Path:
+    return root / RAGX_DIR / "index.db"
+
+
+def vectors_path(root: Path) -> Path:
+    return root / RAGX_DIR / "vectors.hnsw"
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    out = {k: dict(v) for k, v in base.items()}
+    for section, values in override.items():
+        out.setdefault(section, {}).update(values)
+    return out
+
+
+def _coerce(section: str, key: str, value: Any) -> Any:
+    """Coerce a (usually string) value to the type of its DEFAULTS entry."""
+    current = DEFAULTS[section][key]
+    if isinstance(current, bool):
+        return str(value).lower() in ("1", "true", "yes", "on")
+    if isinstance(current, int) and not isinstance(current, bool):
+        return int(value)
+    if isinstance(current, float):
+        return float(value)
+    if isinstance(current, list) and isinstance(value, str):
+        return [v.strip() for v in value.split(",") if v.strip()]
+    return value
+
+
+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()
+    if not path.exists():
+        return {}
+    with path.open("rb") as f:
+        try:
+            data = tomllib.load(f)
+        except tomllib.TOMLDecodeError as exc:
+            raise RagxError(f"malformed {path}: {exc}") from exc
+    for section, values in data.items():
+        if section not in PROVIDER_SECTIONS:
+            raise RagxError(
+                f"{path}: section [{section}] not allowed — only {', '.join(PROVIDER_SECTIONS)}"
+            )
+        for key in values:
+            if key not in DEFAULTS[section]:
+                raise RagxError(f"{path}: unknown key {section}.{key}")
+    return data
+
+
+def write_rc_value(dotted: str, value: Any, rc: Path | None = None) -> Any:
+    """Set one provider key in ~/.ragxrc (created if missing). Returns the coerced value."""
+    section, _, key = dotted.partition(".")
+    if not key or section not in DEFAULTS or key not in DEFAULTS[section]:
+        raise RagxError(f"unknown config key: {dotted!r}")
+    if section not in PROVIDER_SECTIONS:
+        raise RagxError(
+            f"{dotted!r} is corpus-level — only {', '.join(PROVIDER_SECTIONS)} keys go in ~/.ragxrc"
+        )
+    path = rc if rc is not None else rc_path()
+    data = load_rc(path)
+    coerced = _coerce(section, key, value)
+    data.setdefault(section, {})[key] = coerced
+    with path.open("wb") as f:
+        tomli_w.dump(data, f)
+    return coerced
+
+
+class Config:
+    """Two-level (section.key) config: DEFAULTS < corpus config.toml < ~/.ragxrc.
+
+    `data` is the effective merged view; `file_data` is the raw corpus file so that
+    `save` never bakes rc overrides into the corpus config.
+    """
+
+    def __init__(self, data: dict[str, dict[str, Any]], file_data: dict | None = None):
+        self.data = data
+        self.file_data = file_data if file_data is not None else data
+
+    @classmethod
+    def load(cls, root: Path, rc: Path | None = None) -> Config:
+        path = config_path(root)
+        file_data: dict = {}
+        if path.exists():
+            with path.open("rb") as f:
+                file_data = tomllib.load(f)
+        rc_data = load_rc(rc)
+        for section, values in rc_data.items():
+            for key, rc_value in values.items():
+                corpus_value = file_data.get(section, {}).get(key)
+                if corpus_value is not None and corpus_value != rc_value:
+                    log.warning(
+                        "~/.ragxrc overrides %s.%s: %r (corpus) -> %r (rc)",
+                        section, key, corpus_value, rc_value,
+                    )
+        return cls(_deep_merge(DEFAULTS, _deep_merge(file_data, rc_data)), file_data)
+
+    def get(self, dotted: str) -> Any:
+        section, _, key = dotted.partition(".")
+        if not key:
+            raise RagxError(f"config keys are 'section.key', got: {dotted!r}")
+        try:
+            return self.data[section][key]
+        except KeyError:
+            raise RagxError(f"unknown config key: {dotted!r}") from None
+
+    def set(self, dotted: str, value: Any) -> None:
+        section, _, key = dotted.partition(".")
+        if not key or section not in DEFAULTS or key not in DEFAULTS[section]:
+            raise RagxError(f"unknown config key: {dotted!r}")
+        coerced = _coerce(section, key, value)
+        self.data.setdefault(section, {})[key] = coerced
+        if self.file_data is not self.data:
+            self.file_data.setdefault(section, {})[key] = coerced
+
+    def save(self, root: Path) -> None:
+        path = config_path(root)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("wb") as f:
+            tomli_w.dump(_deep_merge(DEFAULTS, self.file_data), f)
+
+
+def write_default_config(root: Path) -> Path:
+    """Create .ragx/ with a default config.toml. Used by `ragx-cli init`."""
+    cfg = Config({k: dict(v) for k, v in DEFAULTS.items()})
+    cfg.save(root)
+    return config_path(root)

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/src/ragx/core/indexer.py

@@ -109,7 +109,7 @@ def _check_manifest(store: Store, embedder: Embedder, *, allow_rewrite: bool) ->
     if prev and prev != embedder.model and not allow_rewrite:
         raise ManifestMismatchError(
             f"index was built with {prev!r} but config says {embedder.model!r}; "
-            "run a full `ragx index` to rebuild"
+            "run a full `ragx-cli index` to rebuild"
         )
 
 

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/src/ragx/core/query.py

@@ -42,7 +42,7 @@ def _check_model(store: Store, embedder: Embedder) -> None:
     if built_with != embedder.model:
         raise RagxError(
             f"index built with {built_with!r}, config says {embedder.model!r}; "
-            "run `ragx index` to rebuild"
+            "run `ragx-cli index` to rebuild"
         )
 
 

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/src/ragx/providers/registry.py

@@ -33,7 +33,7 @@ def _resolve_api_key(cfg: Config, section: str) -> str | None:
 
 def _resolve_base_url(cfg: Config, section: str) -> str:
     """Honor the conventional OPENAI_BASE_URL env var, but only while `<section>.base_url`
-    is still the built-in default — an explicit `ragx config set` always wins."""
+    is still the built-in default — an explicit `ragx-cli config set` always wins."""
     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:

{ragx_cli-0.1.0 → ragx_cli-0.2.0}/src/ragx/providers/st_reranker.py

@@ -17,7 +17,7 @@ class STReranker:
             from sentence_transformers import CrossEncoder
         except ImportError as exc:
             raise RagxError(
-                "sentence-transformers not installed — install with: uv pip install 'ragx[rerank]'"
+                "sentence-transformers not installed — install with: uv tool install ragx-cli --with ragx-cli[rerank]"
             ) from exc
         self.model = model
         self._encoder = CrossEncoder(model)

ragx_cli-0.2.0/tests/conftest.py

@@ -0,0 +1,13 @@
+"""Shared fixtures. HOME is isolated per-test so a developer's real ~/.ragxrc
+can never leak into the suite (the rc overrides corpus config by design)."""
+
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _isolate_home(tmp_path_factory, monkeypatch):
+    home = tmp_path_factory.mktemp("home")
+    monkeypatch.setenv("HOME", str(home))
+    return home

ragx_cli-0.2.0/tests/test_config_rc.py

@@ -0,0 +1,118 @@
+"""~/.ragxrc: machine-level provider settings that override corpus config (with a warning)."""
+
+from __future__ import annotations
+
+import logging
+import tomllib
+
+import pytest
+from typer.testing import CliRunner
+
+from ragx.cli.app import app
+from ragx.core.config import Config, config_path, load_rc, write_default_config, write_rc_value
+from ragx.core.errors import RagxError
+
+runner = CliRunner()
+
+
+@pytest.fixture
+def rc(_isolate_home):
+    return _isolate_home / ".ragxrc"
+
+
+def test_no_rc_is_a_noop(tmp_path, rc):
+    write_default_config(tmp_path)
+    cfg = Config.load(tmp_path)
+    assert cfg.get("embeddings.model") == "text-embedding-nomic-embed-text-v1.5@q4_k_m"
+
+
+def test_rc_overrides_corpus_and_warns(tmp_path, rc, caplog):
+    write_default_config(tmp_path)
+    rc.write_text('[embeddings]\nmodel = "rc-model"\n')
+    with caplog.at_level(logging.WARNING, logger="ragx.config"):
+        cfg = Config.load(tmp_path)
+    assert cfg.get("embeddings.model") == "rc-model"
+    assert any("~/.ragxrc overrides embeddings.model" in r.getMessage() for r in caplog.records)
+
+
+def test_rc_matching_corpus_value_does_not_warn(tmp_path, rc, caplog):
+    write_default_config(tmp_path)
+    rc.write_text('[rerank]\nmodel = "BAAI/bge-reranker-v2-m3"\n')  # same as default/corpus
+    with caplog.at_level(logging.WARNING, logger="ragx.config"):
+        cfg = Config.load(tmp_path)
+    assert cfg.get("rerank.model") == "BAAI/bge-reranker-v2-m3"
+    assert not caplog.records
+
+
+def test_rc_applies_without_corpus_file(tmp_path, rc, caplog):
+    # .ragx/ exists but no config.toml was written: rc applies silently
+    (tmp_path / ".ragx").mkdir()
+    rc.write_text('[expansion]\nmodel = "rc-llm"\nenabled = false\n')
+    with caplog.at_level(logging.WARNING, logger="ragx.config"):
+        cfg = Config.load(tmp_path)
+    assert cfg.get("expansion.model") == "rc-llm"
+    assert cfg.get("expansion.enabled") is False
+    assert not caplog.records
+
+
+def test_rc_rejects_non_provider_section(tmp_path, rc):
+    write_default_config(tmp_path)
+    rc.write_text("[graph]\nk = 12\n")
+    with pytest.raises(RagxError, match=r"section \[graph\] not allowed"):
+        Config.load(tmp_path)
+
+
+def test_rc_rejects_unknown_key(tmp_path, rc):
+    write_default_config(tmp_path)
+    rc.write_text('[embeddings]\nbogus = "x"\n')
+    with pytest.raises(RagxError, match="unknown key embeddings.bogus"):
+        Config.load(tmp_path)
+
+
+def test_rc_malformed_toml(tmp_path, rc):
+    write_default_config(tmp_path)
+    rc.write_text("not [valid toml")
+    with pytest.raises(RagxError, match="malformed"):
+        Config.load(tmp_path)
+
+
+def test_write_rc_value_creates_coerces_and_rejects(rc):
+    coerced = write_rc_value("embeddings.batch_size", "64")
+    assert coerced == 64
+    assert load_rc(rc) == {"embeddings": {"batch_size": 64}}
+    with pytest.raises(RagxError, match="corpus-level"):
+        write_rc_value("graph.k", "12")
+    with pytest.raises(RagxError, match="unknown config key"):
+        write_rc_value("embeddings.bogus", "x")
+
+
+def test_config_set_does_not_bake_rc_into_corpus(tmp_path, rc):
+    write_default_config(tmp_path)
+    rc.write_text('[embeddings]\nmodel = "rc-model"\n')
+    cfg = Config.load(tmp_path)
+    cfg.set("graph.k", "12")
+    cfg.save(tmp_path)
+    saved = tomllib.loads(config_path(tmp_path).read_text())
+    assert saved["graph"]["k"] == 12
+    assert saved["embeddings"]["model"] == "text-embedding-nomic-embed-text-v1.5@q4_k_m"
+
+
+def test_cli_set_global_and_effective_get(tmp_path, rc, monkeypatch):
+    runner.invoke(app, ["init", str(tmp_path)])
+    monkeypatch.chdir(tmp_path)
+
+    result = runner.invoke(app, ["config", "set", "--global", "embeddings.model", "rc-model"])
+    assert result.exit_code == 0
+    assert "embeddings.model = rc-model" in result.stdout
+    assert load_rc(rc) == {"embeddings": {"model": "rc-model"}}
+
+    result = runner.invoke(app, ["config", "get", "embeddings.model"])
+    assert result.exit_code == 0
+    assert result.stdout.strip() == "rc-model"
+
+
+def test_cli_set_global_rejects_corpus_key(tmp_path, monkeypatch):
+    runner.invoke(app, ["init", str(tmp_path)])
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["config", "set", "--global", "graph.k", "12"])
+    assert result.exit_code == 2

ragx_cli-0.1.0/src/ragx/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"

ragx_cli-0.1.0/src/ragx/core/config.py

@@ -1,130 +0,0 @@
-"""Config: .ragx/config.toml is the single source of truth. Written by `init`, read everywhere."""
-
-from __future__ import annotations
-
-import tomllib
-from pathlib import Path
-from typing import Any
-
-import tomli_w
-
-from ragx.core.errors import NotInitializedError, RagxError
-
-RAGX_DIR = ".ragx"
-
-DEFAULTS: dict[str, dict[str, Any]] = {
-    "corpus": {"include": ["**/*"], "exclude": [], "respect_gitignore": True},
-    "chunking": {"size_tokens": 800, "overlap": 0.15},
-    "graph": {"k": 8, "min_edge_sim": 0.55},
-    "traversal": {"hops": 2, "decay": 0.5, "query_floor": 0.35, "max_frontier": 150},
-    "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",
-        "model": "text-embedding-nomic-embed-text-v1.5@q4_k_m",
-        "doc_prefix": "search_document: ",
-        "query_prefix": "search_query: ",
-        "batch_size": 32,
-        "api_key_env": "",  # NAME of an env var holding the API key; empty = no auth header
-    },
-    "expansion": {
-        "enabled": True,
-        "provider": "openai",
-        "base_url": "http://localhost:1234/v1",
-        "model": "mlx-community/Ornith-1.0-35B-3bit",
-        "variants": 3,
-        "hyde": True,
-        "api_key_env": "",
-    },
-    "rerank": {"enabled": True, "provider": "sentence-transformers", "model": "BAAI/bge-reranker-v2-m3"},
-    "query": {"top": 8, "max_chunk_chars": 1200},
-}
-
-
-def find_root(start: Path | None = None) -> Path | None:
-    """Walk up from `start` (default cwd) looking for a .ragx/ directory."""
-    cur = (start or Path.cwd()).resolve()
-    for p in [cur, *cur.parents]:
-        if (p / RAGX_DIR).is_dir():
-            return p
-    return None
-
-
-def require_root(start: Path | None = None) -> Path:
-    root = find_root(start)
-    if root is None:
-        raise NotInitializedError("no .ragx/ found — run `ragx init` first")
-    return root
-
-
-def config_path(root: Path) -> Path:
-    return root / RAGX_DIR / "config.toml"
-
-
-def db_path(root: Path) -> Path:
-    return root / RAGX_DIR / "index.db"
-
-
-def vectors_path(root: Path) -> Path:
-    return root / RAGX_DIR / "vectors.hnsw"
-
-
-def _deep_merge(base: dict, override: dict) -> dict:
-    out = {k: dict(v) for k, v in base.items()}
-    for section, values in override.items():
-        out.setdefault(section, {}).update(values)
-    return out
-
-
-class Config:
-    """Two-level (section.key) config with defaults merged under the file's values."""
-
-    def __init__(self, data: dict[str, dict[str, Any]]):
-        self.data = data
-
-    @classmethod
-    def load(cls, root: Path) -> Config:
-        path = config_path(root)
-        file_data: dict = {}
-        if path.exists():
-            with path.open("rb") as f:
-                file_data = tomllib.load(f)
-        return cls(_deep_merge(DEFAULTS, file_data))
-
-    def get(self, dotted: str) -> Any:
-        section, _, key = dotted.partition(".")
-        if not key:
-            raise RagxError(f"config keys are 'section.key', got: {dotted!r}")
-        try:
-            return self.data[section][key]
-        except KeyError:
-            raise RagxError(f"unknown config key: {dotted!r}") from None
-
-    def set(self, dotted: str, value: Any) -> None:
-        section, _, key = dotted.partition(".")
-        if not key or section not in DEFAULTS or key not in DEFAULTS[section]:
-            raise RagxError(f"unknown config key: {dotted!r}")
-        current = DEFAULTS[section][key]
-        if isinstance(current, bool):
-            value = str(value).lower() in ("1", "true", "yes", "on")
-        elif isinstance(current, int) and not isinstance(current, bool):
-            value = int(value)
-        elif isinstance(current, float):
-            value = float(value)
-        elif isinstance(current, list) and isinstance(value, str):
-            value = [v.strip() for v in value.split(",") if v.strip()]
-        self.data.setdefault(section, {})[key] = value
-
-    def save(self, root: Path) -> None:
-        path = config_path(root)
-        path.parent.mkdir(parents=True, exist_ok=True)
-        with path.open("wb") as f:
-            tomli_w.dump(self.data, f)
-
-
-def write_default_config(root: Path) -> Path:
-    """Create .ragx/ with a default config.toml. Used by `ragx init`."""
-    cfg = Config({k: dict(v) for k, v in DEFAULTS.items()})
-    cfg.save(root)
-    return config_path(root)