ragx-cli 0.9.0__tar.gz → 0.10.0__tar.gz

{ragx_cli-0.9.0 → ragx_cli-0.10.0}/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.10.0] — 2026-10-21
+
+### Added
+
+- `ragx-cli index --edges-only` — rebuilds sub-chunks, graph edges and communities from the
+  stored chunks per the current `[graph]` config, without re-chunking or re-embedding files.
+  Lets an existing index switch `graph.edge_source` (or `subchunk_size_tokens`) cheaply: chunk
+  embeddings and the vector index are kept; a chunk that stays whole reuses its own stored
+  vector, so only the sub-chunk pieces a split chunk actually produces go through the embedder.
+  Mutually exclusive with `--full`/`--changed`. The incremental-index manifest mismatch message
+  for `edge_source`/`subchunk_size_tokens` now also suggests `--edges-only`.
+
+### Changed
+
+- `ragx-cli web` no longer requires an index built with `graph.edge_source = "subchunk"`: it
+  renders whatever edges the index has — sub-chunk similarity when the index has them, otherwise
+  the stored whole-chunk cosine edges. An index with zero edges renders as a node-only cloud.
+
+### Fixed
+
+- `ragx-cli web` layout: ForceAtlas2 now uses edge weights (`edgeWeightInfluence = 1`), so more
+  similar chunks sit closer together. Before, every edge pulled equally.
+
 ## [0.9.0] — 2026-10-21
 
 ### Added

{ragx_cli-0.9.0 → ragx_cli-0.10.0}/CLAUDE.md

@@ -73,8 +73,10 @@ src/ragx/
     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
-    graph_export.py #  build_graph: ragx.graph.v1 payload for `web`; fails loud unless the
-                   #   index's stored edge_source is "subchunk" (see Flows)
+    graph_export.py #  build_graph: ragx.graph.v1 payload for `web`; renders whatever edges the
+                   #   index has, subchunk or chunk-mode cosine (see Flows)
+    reedge.py      #   rebuild_edges: `index --edges-only` — rebuilds sub-chunks/edges/
+                   #   communities from stored chunks, no re-chunk/re-embed (see Flows)
   providers/       # base.py protocols (Embedder/Generator/Reranker); openai_compat.py;
                    # st_reranker.py; lmstudio_process.py (LM Studio autostart);
                    # llama_process.py (managed llama-server lifecycle) +
@@ -88,7 +90,7 @@ src/ragx/
                    # handlers.py (routing), query_runner.py (lazy providers, lock-serialized
                    # queries), static_files.py (path-traversal-safe static serving);
                    # static/ (frontend-owned: index.html, JS/CSS, vendored sigma.js)
-tests/             # 295 tests; mocked HTTP (respx), FakeEmbedder integration tests, no live network
+tests/             # 301 tests; mocked HTTP (respx), FakeEmbedder integration tests, no live network
 ```
 
 ## Flows
@@ -108,8 +110,10 @@ max cos over sub-chunk pairs; edges with whole-chunk cos ≥ `graph.near_dup_sim
 Query side untouched. In subchunk mode `graph.k` means links per SUB-chunk (no per-chunk cap —
 edge budget scales with concept count; graph gets ~1.4x denser at the 256-tok default). The
 manifest guards `edge_source`/`subchunk_size_tokens` like the embedding model — an incremental
-`index` after a flip fails loud, naming the old/new value; `index --full` rebuilds, or pin the
-old value in `ragx.toml`. Rationale + literature: `research/fine-grained-sub-chunk-edges-*.md`.
+`index` after a flip fails loud, naming the old/new value; `index --edges-only` (`core/reedge.py`)
+rebuilds just sub-chunks/edges/communities from the stored chunks — no re-chunk/re-embed, reusing
+each whole chunk's stored vector — or `index --full` rebuilds everything, or pin the old value in
+`ragx.toml`. Rationale + literature: `research/fine-grained-sub-chunk-edges-*.md`.
 MEASURED 2026-07-12 (`.lab` experiments #10–#11): on the scoped notes eval corpus the dense
 concept graph at hops2 TIES the tuned chunk-graph baseline (r@10 .923 / MRR .718 vs .717) at
 ~4.5x index embed cost (128-tok sub-chunks) — no win because the corpus's short single-topic
@@ -144,9 +148,9 @@ Each result chunk also carries grep-style `-B`/`-A`/`-C` context lines (`core/co
 reads since no text is shown.
 
 **Web** (`ragx-cli web`): builds the `ragx.graph.v1` payload once at startup (`graph_export.py`
-— requires the index's stored `edge_source` to be `"subchunk"`, fails loud otherwise) and serves
-it plus `/api/chunk/{id}` and `/api/query` (same pipeline as `query`, providers built lazily and
-cached, one query at a time behind a lock) over stdlib `http.server`.
+— renders the index's stored edges, sub-chunk or chunk-mode cosine; fails loud only when no
+index exists) and serves it plus `/api/chunk/{id}` and `/api/query` (same pipeline as `query`,
+providers built lazily and cached, one query at a time behind a lock) over stdlib `http.server`.
 
 ## State & benchmarks (as of 2026-07-10)
 
@@ -201,7 +205,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` (295 pass, ~7 s) ·
+`uv sync --group dev --extra rerank` · `uv run pytest -q` (300 pass + 1 skipped, ~9 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.9.0 → ragx_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ragx-cli
-Version: 0.9.0
+Version: 0.10.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
@@ -52,6 +52,7 @@ ragx-cli init                  # create ragx.toml next to your corpus (interacti
 ragx-cli index                 # chunk -> embed -> HNSW + kNN similarity graph (incremental after the first run)
 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 index --edges-only    # rebuild sub-chunks/edges/communities only; keeps chunk embeddings
 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)
@@ -97,8 +98,10 @@ chunk mixing several concepts gets one sharp edge per concept instead of a dilut
 between near-duplicate chunks (whole-chunk cosine ≥ `near_dup_sim`) are dropped — those are the
 measured precision-killers. Costs ~2× more embedding calls at index time than `edge_source =
 "chunk"`; retrieval units, traversal, and query flow are unchanged. Switching `edge_source` (or
-the sub-chunk size) requires `index --full`; incremental runs fail loud on the mismatch, naming
-the old/new value and the fix. Literature grounding:
+the sub-chunk size) requires either `index --edges-only` (cheap: rebuilds sub-chunks, edges and
+communities from the stored chunks — chunk embeddings and the HNSW index are kept) or
+`index --full`; incremental runs fail loud on the mismatch, naming the old/new value and both
+fixes. Literature grounding:
 `research/fine-grained-sub-chunk-edges-with-coarse-chunk-nodes-multi-granularity-graph-rag-literature-validation.md`.
 In this mode `k` counts links per *sub-chunk* with no per-chunk cap, so the graph is denser and
 shallower traversal suffices (the default `hops=2` already matches this). Quality ties
@@ -129,17 +132,24 @@ flowchart TD
 re-embeds only new/modified files, drops deleted ones, and repairs only the edge lists those
 chunks touch. Content hashes make `touch`-ed but unchanged files free, and include/exclude glob
 changes converge to the same file set a rebuild would produce. `--full` rebuilds from scratch;
-changing `embeddings.model`, `chunking.*`, or `graph.edge_source`/`subchunk_size_tokens` requires
-it — incremental runs fail loud on the manifest mismatch, naming the changed key and its old/new
-value. `ragx-cli status` reports **drift** (files new/changed/deleted since the last index) so
-you can see when a re-index is due without running one.
+changing `embeddings.model` or `chunking.*` requires it — incremental runs fail loud on the
+manifest mismatch, naming the changed key and its old/new value. Changing `graph.edge_source`/
+`subchunk_size_tokens` alone is cheaper: `--edges-only` rebuilds just the sub-chunks, edges and
+communities from the chunks already stored — it skips chunking and embedding entirely, reusing
+each chunk's stored vector (via the HNSW index) for chunks that stay whole, and only calls the
+embedder for the sub-chunk pieces a long chunk splits into. It fails loud the same way `--full`
+does if `embeddings.model`/`chunking.*` don't match the stored manifest (those invalidate the
+chunks it reuses), but `edge_source`/`subchunk_size_tokens` are exactly what it's meant to change.
+`ragx-cli status` reports **drift** (files new/changed/deleted since the last index) so you can
+see when a re-index is due without running one.
 
 Upgrading from an older `ragx-cli` after a default change (e.g. the `graph.edge_source` flip to
 `"subchunk"`): `ragx-cli init` always writes every `[graph]` key explicitly into `ragx.toml`
 (`Config.save` bakes the full default set, not just overrides), so an init-created corpus already
 pins its `edge_source`/`subchunk_size_tokens` and is unaffected by a later default change. Only a
 hand-written `ragx.toml` missing those keys picks up the new default; its next incremental
-`index` then fails loud — `index --full` rebuilds, or pin the old value back in `ragx.toml`.
+`index` then fails loud — `index --edges-only` rebuilds just the graph (cheapest), `index --full`
+rebuilds everything, or pin the old value back in `ragx.toml`.
 
 ### Querying
 
@@ -477,11 +487,11 @@ anything. If a run dies with "connection refused", `doctor` names the stage and
 ragx-cli web [--host 127.0.0.1] [--port 8765] [--open/--no-open]
 ```
 
-Requires an index built with `graph.edge_source = "subchunk"` (the default) — the graph view
-renders stored edge weights as sub-chunk similarity, and a `"chunk"`-mode index's whole-chunk
-cosine weights would mislabel what the edges mean. Fails loud (exit 2) naming the mismatch, or
-when no index exists yet. `--open` (default) launches the browser; Ctrl-C shuts the server down
-cleanly.
+Renders whatever edges the index has: sub-chunk similarity when it was built with
+`graph.edge_source = "subchunk"` (the default), whole-chunk cosine when `"chunk"`. Fails loud
+(exit 2) only when no index exists yet. To switch an existing index to sub-chunk edges without a
+full re-embed, set the `[graph]` keys in `ragx.toml` and run `ragx-cli index --edges-only`.
+`--open` (default) launches the browser; Ctrl-C shuts the server down cleanly.
 
 Endpoints (JSON; errors are `{"error": "<message>"}`):
 

{ragx_cli-0.9.0 → ragx_cli-0.10.0}/README.md

@@ -24,6 +24,7 @@ ragx-cli init                  # create ragx.toml next to your corpus (interacti
 ragx-cli index                 # chunk -> embed -> HNSW + kNN similarity graph (incremental after the first run)
 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 index --edges-only    # rebuild sub-chunks/edges/communities only; keeps chunk embeddings
 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)
@@ -69,8 +70,10 @@ chunk mixing several concepts gets one sharp edge per concept instead of a dilut
 between near-duplicate chunks (whole-chunk cosine ≥ `near_dup_sim`) are dropped — those are the
 measured precision-killers. Costs ~2× more embedding calls at index time than `edge_source =
 "chunk"`; retrieval units, traversal, and query flow are unchanged. Switching `edge_source` (or
-the sub-chunk size) requires `index --full`; incremental runs fail loud on the mismatch, naming
-the old/new value and the fix. Literature grounding:
+the sub-chunk size) requires either `index --edges-only` (cheap: rebuilds sub-chunks, edges and
+communities from the stored chunks — chunk embeddings and the HNSW index are kept) or
+`index --full`; incremental runs fail loud on the mismatch, naming the old/new value and both
+fixes. Literature grounding:
 `research/fine-grained-sub-chunk-edges-with-coarse-chunk-nodes-multi-granularity-graph-rag-literature-validation.md`.
 In this mode `k` counts links per *sub-chunk* with no per-chunk cap, so the graph is denser and
 shallower traversal suffices (the default `hops=2` already matches this). Quality ties
@@ -101,17 +104,24 @@ flowchart TD
 re-embeds only new/modified files, drops deleted ones, and repairs only the edge lists those
 chunks touch. Content hashes make `touch`-ed but unchanged files free, and include/exclude glob
 changes converge to the same file set a rebuild would produce. `--full` rebuilds from scratch;
-changing `embeddings.model`, `chunking.*`, or `graph.edge_source`/`subchunk_size_tokens` requires
-it — incremental runs fail loud on the manifest mismatch, naming the changed key and its old/new
-value. `ragx-cli status` reports **drift** (files new/changed/deleted since the last index) so
-you can see when a re-index is due without running one.
+changing `embeddings.model` or `chunking.*` requires it — incremental runs fail loud on the
+manifest mismatch, naming the changed key and its old/new value. Changing `graph.edge_source`/
+`subchunk_size_tokens` alone is cheaper: `--edges-only` rebuilds just the sub-chunks, edges and
+communities from the chunks already stored — it skips chunking and embedding entirely, reusing
+each chunk's stored vector (via the HNSW index) for chunks that stay whole, and only calls the
+embedder for the sub-chunk pieces a long chunk splits into. It fails loud the same way `--full`
+does if `embeddings.model`/`chunking.*` don't match the stored manifest (those invalidate the
+chunks it reuses), but `edge_source`/`subchunk_size_tokens` are exactly what it's meant to change.
+`ragx-cli status` reports **drift** (files new/changed/deleted since the last index) so you can
+see when a re-index is due without running one.
 
 Upgrading from an older `ragx-cli` after a default change (e.g. the `graph.edge_source` flip to
 `"subchunk"`): `ragx-cli init` always writes every `[graph]` key explicitly into `ragx.toml`
 (`Config.save` bakes the full default set, not just overrides), so an init-created corpus already
 pins its `edge_source`/`subchunk_size_tokens` and is unaffected by a later default change. Only a
 hand-written `ragx.toml` missing those keys picks up the new default; its next incremental
-`index` then fails loud — `index --full` rebuilds, or pin the old value back in `ragx.toml`.
+`index` then fails loud — `index --edges-only` rebuilds just the graph (cheapest), `index --full`
+rebuilds everything, or pin the old value back in `ragx.toml`.
 
 ### Querying
 
@@ -449,11 +459,11 @@ anything. If a run dies with "connection refused", `doctor` names the stage and
 ragx-cli web [--host 127.0.0.1] [--port 8765] [--open/--no-open]
 ```
 
-Requires an index built with `graph.edge_source = "subchunk"` (the default) — the graph view
-renders stored edge weights as sub-chunk similarity, and a `"chunk"`-mode index's whole-chunk
-cosine weights would mislabel what the edges mean. Fails loud (exit 2) naming the mismatch, or
-when no index exists yet. `--open` (default) launches the browser; Ctrl-C shuts the server down
-cleanly.
+Renders whatever edges the index has: sub-chunk similarity when it was built with
+`graph.edge_source = "subchunk"` (the default), whole-chunk cosine when `"chunk"`. Fails loud
+(exit 2) only when no index exists yet. To switch an existing index to sub-chunk edges without a
+full re-embed, set the `[graph]` keys in `ragx.toml` and run `ragx-cli index --edges-only`.
+`--open` (default) launches the browser; Ctrl-C shuts the server down cleanly.
 
 Endpoints (JSON; errors are `{"error": "<message>"}`):
 

{ragx_cli-0.9.0 → ragx_cli-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragx-cli"
-version = "0.9.0"
+version = "0.10.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.9.0 → ragx_cli-0.10.0}/skills/ragx-cli/SKILL.md

@@ -35,6 +35,7 @@ ragx-cli query "..." --json --rerank            # higher precision: cross-encode
 echo "..." | ragx-cli query - --json            # long/multiline query from stdin
 ragx-cli index                  # incremental reindex (hash-based, cheap) — the default
 ragx-cli index --full           # full rebuild: re-chunks + re-embeds everything
+ragx-cli index --edges-only     # rebuild sub-chunks/edges/communities only; keeps embeddings
 ```
 
 Other query flags: `--expand` (one LLM call: multi-query + HyDE), `--no-graph` (pure vector),
@@ -60,8 +61,10 @@ default 5). `--no-expand`/`--no-rerank` are deprecated no-ops (both stages are o
   (incremental, safe, converges even after include/exclude glob changes).
 - Changing `embeddings.model`, `chunking.*`, or `graph.edge_source`/`subchunk_size_tokens`
   invalidates the index: commands fail loud on the manifest mismatch, naming the changed
-  key and old/new value. Fix is `ragx-cli index --full` — re-embeds everything, so confirm
-  before running on a large corpus — or pin the old value back in `ragx.toml`.
+  key and old/new value. For an `edge_source`/`subchunk_size_tokens` change, `ragx-cli index
+  --edges-only` is the cheap fix — rebuilds sub-chunks/edges/communities, keeps chunk
+  embeddings. Otherwise `ragx-cli index --full` — re-embeds everything, so confirm before
+  running on a large corpus — or pin the old value back in `ragx.toml`.
 - `ragx-cli models` picks + downloads an embedding/reranker combo. All files download via
   LM Studio; serving is per engine — `--embed-engine llama-server|lm-studio` and
   `--rerank-engine llama-server|sentence-transformers`. With both on `llama-server`

{ragx_cli-0.9.0 → ragx_cli-0.10.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.core.reedge import rebuild_edges
 from ragx.providers import lmstudio_process
 from ragx.providers.registry import make_embedder, make_generator, make_reranker
 
@@ -24,6 +25,12 @@ def register(app: typer.Typer) -> None:
 def index(
     path: Path | None = typer.Argument(None),
     full: bool = typer.Option(False, "--full", help="full rebuild: re-chunk and re-embed everything"),
+    edges_only: bool = typer.Option(
+        False,
+        "--edges-only",
+        help="rebuild sub-chunks, graph edges and communities from the stored chunks per "
+        "the current [graph] config; chunk embeddings and the vector index are kept",
+    ),
     changed: bool = typer.Option(
         False, "--changed", hidden=True, help="deprecated: incremental is now the default"
     ),
@@ -32,13 +39,20 @@ def index(
     """Chunk, embed, and index the corpus (incremental by default; --full rebuilds)."""
     if changed and full:
         fail("--changed and --full are mutually exclusive")
+    if edges_only and full:
+        fail("--edges-only and --full are mutually exclusive")
+    if edges_only and changed:
+        fail("--edges-only and --changed are mutually exclusive")
     if changed:
         print("warning: --changed is deprecated; incremental is now the default", file=sys.stderr)
     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)
+        if edges_only:
+            stats = rebuild_edges(root, cfg, make_embedder(cfg))
+        else:
+            stats = run_index(root, cfg, make_embedder(cfg), full=full)
     except RagxError as exc:
         fail(str(exc))
     doc = {"schema": "ragx.index.v1", **stats.__dict__}

{ragx_cli-0.9.0 → ragx_cli-0.10.0}/src/ragx/core/graph_export.py

@@ -1,14 +1,13 @@
 """Builds the ragx.graph.v1 payload (nodes/edges/communities) for `ragx-cli web`.
 
-Requires an index built with graph.edge_source="subchunk": the viewer renders the
-stored edge weights as sub-chunk similarity, and a whole-chunk-cosine graph (edge_source
-="chunk") would mislabel those edges as concept-level links they aren't."""
+Renders whatever edges the index has: sub-chunk similarity when it was built with
+graph.edge_source="subchunk", whole-chunk cosine when edge_source="chunk". An index with
+zero edges (nodes only) is valid — the viewer just shows an unconnected cloud."""
 
 from __future__ import annotations
 
 from pathlib import Path
 
-from ragx.core.errors import RagxError
 from ragx.core.store import Store
 
 LABEL_MAX_CHARS = 80
@@ -16,12 +15,7 @@ LABEL_MAX_CHARS = 80
 
 def build_graph(root: Path, store: Store) -> dict:
     edge_source = store.get_meta("edge_source")
-    if edge_source != "subchunk":
-        raise RagxError(
-            "ragx-cli web shows sub-chunk edges, but this index was built with "
-            f'edge_source="{edge_source}". Set graph.edge_source = "subchunk" in '
-            "ragx.toml and run ragx-cli index."
-        )
+    sub_size = store.get_meta("subchunk_size_tokens")
 
     chunks = store.get_chunks(store.all_chunk_ids())
     edges = store.all_edges()
@@ -51,7 +45,7 @@ def build_graph(root: Path, store: Store) -> dict:
         "meta": {
             "root": root.name,
             "edge_source": edge_source,
-            "subchunk_size_tokens": int(store.get_meta("subchunk_size_tokens") or 0),
+            "subchunk_size_tokens": int(sub_size) if edge_source == "subchunk" and sub_size else None,
             "embedding_model": store.get_meta("embedding_model"),
             "nodes": len(nodes),
             "edges": len(edge_list),

{ragx_cli-0.9.0 → ragx_cli-0.10.0}/src/ragx/core/indexer.py

@@ -16,7 +16,7 @@ from ragx.core.config import Config, db_path, vectors_path
 from ragx.core.discovery import discover_files, hash_file
 from ragx.core.errors import ManifestMismatchError, RagxError
 from ragx.core.graph import affected_ids, knn_edges, subchunk_knn_edges
-from ragx.core.models import ChunkDraft, FileRecord
+from ragx.core.models import FileRecord
 from ragx.core.store import Store
 from ragx.core.vectors import VectorIndex
 from ragx.providers.base import Embedder
@@ -94,7 +94,7 @@ def run_index(root: Path, cfg: Config, embedder: Embedder, *, full: bool = False
             vectors = embedder.embed_documents([d.text for d in drafts])
             index.add(ids, vectors)
             if edge_source == "subchunk":
-                _embed_subchunks(store, embedder, ids, drafts, vectors, sub_size)
+                _embed_subchunks(store, embedder, ids, [d.text for d in drafts], vectors, sub_size)
             new_ids.extend(ids)
             stats.files_indexed += 1
             stats.chunks_added += len(ids)
@@ -150,9 +150,15 @@ def _check_manifest(
     for key, current in checks:
         prev = store.get_meta(key)
         if prev and prev != str(current) and not allow_rewrite:
+            rebuild_hint = "run `ragx-cli index --full` to rebuild"
+            if key in ("edge_source", "subchunk_size_tokens"):
+                rebuild_hint = (
+                    "run `ragx-cli index --edges-only` to rebuild just the graph (cheaper: "
+                    "keeps chunk embeddings), or `ragx-cli index --full` to rebuild everything"
+                )
             raise ManifestMismatchError(
                 f"index was built with {key}={prev!r} but config says {current!r}; "
-                "run `ragx-cli index --full` to rebuild, or pin the old value "
+                f"{rebuild_hint}, or pin the old value "
                 f"({key} = {prev!r}) in ragx.toml to keep the existing index"
             )
 
@@ -192,18 +198,21 @@ def _embed_subchunks(
     store: Store,
     embedder: Embedder,
     ids: Sequence[int],
-    drafts: Sequence[ChunkDraft],
+    texts: Sequence[str],
     chunk_vectors: Sequence[Sequence[float]],
     sub_size: int,
-) -> None:
-    """Split each chunk into sub-chunks and persist their unit vectors.
-    A chunk that stays whole reuses its own embedding — no extra provider call."""
+) -> tuple[int, int]:
+    """Split each chunk's text into sub-chunks and persist their unit vectors.
+    A chunk that stays whole reuses its own embedding — no extra provider call.
+    Returns (sub-chunks embedded, sub-chunks reused from the chunk embedding)."""
     to_embed: list[str] = []
     spans: list[tuple[int, int, int]] = []  # (chunk_id, start, end) into to_embed
-    for cid, draft, cvec in zip(ids, drafts, chunk_vectors):
-        subs = subchunk_texts(draft.text, sub_size)
+    reused = 0
+    for cid, text, cvec in zip(ids, texts, chunk_vectors):
+        subs = subchunk_texts(text, sub_size)
         if len(subs) == 1:
             store.insert_subchunk_vectors(cid, [_unit(cvec)])
+            reused += 1
         else:
             spans.append((cid, len(to_embed), len(to_embed) + len(subs)))
             to_embed.extend(subs)
@@ -211,6 +220,7 @@ def _embed_subchunks(
         vectors = embedder.embed_documents(to_embed)
         for cid, start, end in spans:
             store.insert_subchunk_vectors(cid, [_unit(v) for v in vectors[start:end]])
+    return len(to_embed), reused
 
 
 def _subchunk_edge_fn(

ragx_cli-0.10.0/src/ragx/core/reedge.py

@@ -0,0 +1,106 @@
+"""Rebuild sub-chunks, graph edges and communities from stored chunks, without re-chunking
+or re-embedding files. Backs `ragx-cli index --edges-only`, for switching `graph.edge_source`
+(or `subchunk_size_tokens`) on an existing index without paying for a full re-embed."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from ragx.core.communities import leiden_communities
+from ragx.core.config import Config, db_path
+from ragx.core.errors import ManifestMismatchError, RagxError
+from ragx.core.graph import knn_edges
+from ragx.core.indexer import IndexStats, _embed_subchunks, _open_vectors, _subchunk_edge_fn
+from ragx.core.store import Store
+from ragx.providers.base import Embedder
+
+log = logging.getLogger("ragx.index")
+
+_BATCH = 300
+
+
+def rebuild_edges(root: Path, cfg: Config, embedder: Embedder) -> IndexStats:
+    """Rebuild sub-chunks (if `graph.edge_source == "subchunk"`), graph edges and communities
+    from the chunks already stored at `root`, per the current [graph] config. Chunk embeddings
+    and the vector index are untouched: a chunk that stays whole reuses its own stored vector —
+    no provider call re-embeds it."""
+    edge_source = cfg.get("graph.edge_source")
+    if edge_source not in ("chunk", "subchunk"):
+        raise RagxError(f"graph.edge_source must be 'chunk' or 'subchunk', got {edge_source!r}")
+    sub_size = cfg.get("graph.subchunk_size_tokens")
+    size_tokens = cfg.get("chunking.size_tokens")
+    overlap = cfg.get("chunking.overlap")
+
+    if not db_path(root).exists():
+        raise RagxError("no index found — run `ragx-cli index` first")
+    with Store(db_path(root)) as store:
+        if store.chunk_count() == 0:
+            raise RagxError("no index found — run `ragx-cli index` first")
+        _check_manifest(store, embedder, size_tokens, overlap)
+
+        dim = embedder.dimension()
+        index = _open_vectors(root, dim)
+        store.clear_subchunks()
+        store.clear_edges()
+
+        all_ids = store.all_chunk_ids()
+        k, min_sim = cfg.get("graph.k"), cfg.get("graph.min_edge_sim")
+        embedded = reused = 0
+        if edge_source == "subchunk":
+            for i in range(0, len(all_ids), _BATCH):
+                batch = all_ids[i : i + _BATCH]
+                texts = [c.text for c in store.get_chunks(batch)]
+                vectors = index.get_vectors(batch)
+                n_embed, n_reuse = _embed_subchunks(store, embedder, batch, texts, vectors, sub_size)
+                embedded += n_embed
+                reused += n_reuse
+            edge_fn = _subchunk_edge_fn(store, index, dim, k, min_sim, cfg.get("graph.near_dup_sim"))
+        else:
+            def edge_fn(ids_: list[int]) -> dict[int, list[tuple[int, float]]]:
+                return knn_edges(index, ids_, k, min_sim)
+
+        edges = edge_fn(all_ids)
+        for src, nbrs in edges.items():
+            store.replace_edges(src, nbrs)
+
+        assignments = leiden_communities(
+            store.all_edges(),
+            resolution=cfg.get("communities.resolution"),
+            seed=cfg.get("communities.seed"),
+        )
+        store.replace_communities(assignments)
+
+        store.set_meta("edge_source", edge_source)
+        store.set_meta("subchunk_size_tokens", str(sub_size))
+
+        stats = IndexStats(
+            edges_total=store.edge_count(),
+            communities_total=len(set(assignments.values())),
+        )
+        if edge_source == "subchunk":
+            log.info("sub-chunks: %d embedded, %d reused", embedded, reused)
+        log.info(
+            "edges-only rebuild: %d chunks, %d edges, %d communities",
+            len(all_ids), stats.edges_total, stats.communities_total,
+        )
+        return stats
+
+
+def _check_manifest(store: Store, embedder: Embedder, size_tokens: int, overlap: float) -> None:
+    """embedding_model/chunk_size_tokens/chunk_overlap must match: edges are rebuilt from
+    stored chunk texts and reused chunk embeddings, which are only valid for the embedder and
+    chunking the index was built with. edge_source/subchunk_size_tokens are NOT checked here —
+    changing them is the point of --edges-only."""
+    checks = [
+        ("embedding_model", embedder.model),
+        ("chunk_size_tokens", str(size_tokens)),
+        ("chunk_overlap", str(overlap)),
+    ]
+    for key, current in checks:
+        prev = store.get_meta(key)
+        if prev and prev != str(current):
+            raise ManifestMismatchError(
+                f"index was built with {key}={prev!r} but config says {current!r}; "
+                "run `ragx-cli index --full` to rebuild"
+            )

{ragx_cli-0.9.0 → ragx_cli-0.10.0}/src/ragx/core/store.py

@@ -166,6 +166,10 @@ class Store:
             "SELECT chunk_id, vector FROM subchunks ORDER BY chunk_id, id"
         ).fetchall()
 
+    def clear_subchunks(self) -> None:
+        self.conn.execute("DELETE FROM subchunks")
+        self.conn.commit()
+
     # -- edges (undirected; stored normalized src < dst) -----------------
 
     def replace_edges(self, src: int, neighbors: Sequence[tuple[int, float]]) -> None:
@@ -199,6 +203,10 @@ class Store:
     def edge_count(self) -> int:
         return self.conn.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
 
+    def clear_edges(self) -> None:
+        self.conn.execute("DELETE FROM edges")
+        self.conn.commit()
+
     def all_edges(self) -> list[tuple[int, int, float]]:
         return self.conn.execute("SELECT src, dst, weight FROM edges ORDER BY src, dst").fetchall()
 

{ragx_cli-0.9.0 → ragx_cli-0.10.0}/src/ragx/web/static/js/layout.js

@@ -63,6 +63,7 @@ export function savePositions(graph, key) {
 function settingsFor(graph) {
   const settings = FA2.inferSettings(graph);
   settings.barnesHutOptimize = graph.order > 2000;
+  settings.edgeWeightInfluence = 1; // edge `weight` (similarity) pulls stronger links closer
   return settings;
 }
 

{ragx_cli-0.9.0 → ragx_cli-0.10.0}/src/ragx/web/static/js/main.js

@@ -23,12 +23,15 @@ function showPanel(nodes) {
 }
 
 function renderMeta(meta) {
+  const edgeSource = meta.edge_source === "subchunk"
+    ? `subchunk (${meta.subchunk_size_tokens} tok)`
+    : "chunk (whole-chunk cosine)";
   const items = [
     ["corpus", meta.root],
     ["chunks", fmtInt(meta.nodes)],
     ["edges", fmtInt(meta.edges)],
     ["communities", fmtInt(meta.communities)],
-    ["edge source", `${meta.edge_source} (${meta.subchunk_size_tokens} tok)`],
+    ["edge source", edgeSource],
     ["embedding", meta.embedding_model],
   ];
   $("#meta").replaceChildren(...items.map(([k, v]) =>

{ragx_cli-0.9.0 → ragx_cli-0.10.0}/tests/test_cli.py

@@ -251,6 +251,20 @@ def test_index_changed_and_full_mutually_exclusive(tmp_path, monkeypatch):
     assert result.exit_code == 2
 
 
+def test_index_edges_only_and_full_mutually_exclusive(tmp_path, monkeypatch):
+    runner.invoke(app, ["init", str(tmp_path)])
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["index", "--edges-only", "--full"])
+    assert result.exit_code == 2
+
+
+def test_index_edges_only_and_changed_mutually_exclusive(tmp_path, monkeypatch):
+    runner.invoke(app, ["init", str(tmp_path)])
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["index", "--edges-only", "--changed"])
+    assert result.exit_code == 2
+
+
 def test_status_without_init(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
     result = runner.invoke(app, ["status"])