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

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

@@ -92,8 +92,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

{ragx_cli-0.1.0 → ragx_cli-0.1.1}/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.1.1}/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.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragx-cli
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -67,7 +67,7 @@ uses a local sentence-transformers cross-encoder (`ragx-cli[rerank]` extra). Eve
   - [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)
   - [Configuration](#configuration)
-  - [Features & roadmap](#features--roadmap)
+  - [Features \& roadmap](#features--roadmap)
 
 
 ## How it works

{ragx_cli-0.1.0 → ragx_cli-0.1.1}/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
@@ -41,7 +41,7 @@ uses a local sentence-transformers cross-encoder (`ragx-cli[rerank]` extra). Eve
   - [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)
   - [Configuration](#configuration)
-  - [Features & roadmap](#features--roadmap)
+  - [Features \& roadmap](#features--roadmap)
 
 
 ## How it works

{ragx_cli-0.1.0 → ragx_cli-0.1.1}/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.1.1}/pyproject.toml

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

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

{ragx_cli-0.1.0 → ragx_cli-0.1.1}/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
 

{ragx_cli-0.1.0 → ragx_cli-0.1.1}/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.1.1}/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.1.0 → ragx_cli-0.1.1}/src/ragx/core/config.py

@@ -54,7 +54,7 @@ def find_root(start: Path | None = None) -> Path | 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")
+        raise NotInitializedError("no .ragx/ found — run `ragx-cli init` first")
     return root
 
 
@@ -124,7 +124,7 @@ class Config:
 
 
 def write_default_config(root: Path) -> Path:
-    """Create .ragx/ with a default config.toml. Used by `ragx init`."""
+    """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.1.1}/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.1.1}/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.1.1}/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.1.1}/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.1.0/src/ragx/__init__.py

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