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

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

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

{ragx_cli-0.1.1 → 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.
@@ -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.1 → ragx_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragx-cli
-Version: 0.1.1
+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
@@ -63,9 +63,11 @@ 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)
 
@@ -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.1 → ragx_cli-0.2.0}/README.md

@@ -37,9 +37,11 @@ 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)
 
@@ -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.1 → ragx_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragx-cli"
-version = "0.1.1"
+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.2.0/src/ragx/__init__.py

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

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

@@ -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.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.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.1/src/ragx/__init__.py

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

ragx_cli-0.1.1/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-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
-
-
-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-cli init`."""
-    cfg = Config({k: dict(v) for k, v in DEFAULTS.items()})
-    cfg.save(root)
-    return config_path(root)