conexus 2.4.0__tar.gz → 2.4.2__tar.gz

{conexus-2.4.0 → conexus-2.4.2}/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "nx",
       "source": "./nx",
       "description": "Self-hosted three-tier knowledge management with 15 specialized agents, semantic search, and RDR decision tracking for Claude Code.",
-      "version": "2.4.0"
+      "version": "2.4.2"
     }
   ]
 }

{conexus-2.4.0 → conexus-2.4.2}/CHANGELOG.md

@@ -6,6 +6,22 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.4.2] - 2026-03-25
+
+### Docs
+- **Python 3.14 troubleshooting** — `uv tool update` reuses the existing
+  environment's Python, so upgrading under 3.14 doesn't auto-switch to 3.13
+  despite the `requires-python` cap. Documented `--force --python 3.13` as
+  the fix. Added `head -1 $(which nx)` diagnostic.
+
+## [2.4.1] - 2026-03-24
+
+### Fixed
+- **`--collection` flag bypass of `t3_collection_name()`** — `nx index pdf --collection knowledge` now correctly normalizes to `knowledge__knowledge`, matching search conventions. Previously created bare collections invisible to `nx search` with wrong embedding model.
+- **`memory promote --collection` same bug** — bare collection names in `nx memory promote` now normalized via `t3_collection_name()`.
+- **Updated `--collection` help text** — no longer says "Fully-qualified" since bare names are now accepted and auto-normalized.
+- **Updated CCE post-mortem** — linked RDR-040 resolution and documented the `--collection` naming variant.
+
 ## [2.4.0] - 2026-03-24
 
 ### Added

{conexus-2.4.0 → conexus-2.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conexus
-Version: 2.4.0
+Version: 2.4.2
 Summary: Self-hosted semantic search and knowledge management for LLM-driven development
 Project-URL: Homepage, https://github.com/Hellblazer/nexus
 Project-URL: Repository, https://github.com/Hellblazer/nexus

{conexus-2.4.0 → conexus-2.4.2}/docs/getting-started.md

@@ -143,7 +143,14 @@ To force local mode even when cloud credentials exist: `NX_LOCAL=1`.
 
 **`nx` command not found** — Make sure `~/.local/bin` is on your PATH. Run `uv tool install conexus` again and check the output for the install location.
 
-**Crash on startup (Python 3.14)** — Nexus requires Python 3.12–3.13. If `python3 --version` shows 3.14, install 3.13: `uv python install 3.13`, then reinstall: `uv tool install conexus --force`.
+**Crash on startup (Python 3.14)** — Nexus requires Python 3.12–3.13. Check your nx install's Python with: `head -1 $(which nx)`. If it shows `python3.14`, the tool was installed under the wrong Python. Fix:
+
+```bash
+uv python install 3.13
+uv tool install conexus --force --python 3.13
+```
+
+Note: `uv tool update` reuses the existing environment's Python — it won't switch from 3.14 to 3.13 automatically. You must use `--force --python 3.13` to rebuild the environment.
 
 **`nx doctor` reports credentials not set** — Expected for local mode. Only needed if you want cloud embeddings — run `nx config init`.
 
@@ -151,7 +158,7 @@ To force local mode even when cloud credentials exist: `NX_LOCAL=1`.
 
 **`nx index repo .` fails with "credentials not set"** — In cloud mode, indexing requires T3 credentials. Run `nx config init` first, or use local mode (no credentials needed).
 
-**`import voyageai` error** — Reinstall: `uv tool install conexus --force`. If on Python 3.14, downgrade to 3.13: `uv python install 3.13` then reinstall.
+**`import voyageai` or Pydantic v1 error** — The tool is running under Python 3.14. Fix: `uv tool install conexus --force --python 3.13` (install 3.13 first with `uv python install 3.13` if needed).
 
 **First index is slow or hits a rate limit** — Large repos may take a few minutes. Add `--monitor` for per-file progress. Re-running is safe — unchanged files are skipped.
 

conexus-2.4.2/docs/postmortem/2026-03-24-pdf-index-fix-not-applied.md

@@ -0,0 +1,142 @@
+# Postmortem: nx index pdf fix not applied in v2.4.0
+
+**Date**: 2026-03-24
+**Severity**: High — believed-fixed bug still present in installed version
+**Related**: [2026-03-23 original postmortem](2026-03-23-pdf-index-collection-mismatch.md)
+**Impact**: Round-trip test after "fix" confirmed the bug persists in nx 2.4.0
+
+## Summary
+
+After the 2026-03-23 incident (10,036 chunks indexed to wrong collection with wrong embedding model), a fix was reported as applied to the nx codebase. However, a round-trip verification test on 2026-03-24 confirmed the fix is **NOT present** in the installed `nx` version 2.4.0. The bug remains: `nx index pdf --collection knowledge` still creates a bare `"knowledge"` collection with `voyage-4` embeddings instead of `"knowledge__knowledge"` with `voyage-context-3`.
+
+## Reproduction Steps
+
+### Prerequisites
+- nx version 2.4.0 installed (`nx --version`)
+- Chroma Cloud configured (`~/.config/nexus/config.yml` has `chroma_api_key`)
+- A test PDF file (any small PDF will do)
+
+### Step 1: Confirm baseline state
+```bash
+# Check current knowledge collection
+nx collection info knowledge__knowledge
+# Expected: Documents: N, Index model: voyage-context-3
+```
+
+### Step 2: Index a test PDF
+```bash
+nx index pdf /path/to/test.pdf --collection knowledge
+# Output: "Indexed N chunk(s)." — appears successful
+```
+
+### Step 3: Check if chunks landed in the right collection
+```bash
+nx collection info knowledge__knowledge
+# EXPECTED (if fixed): Documents: N + chunks
+# ACTUAL (bug): Documents: N (unchanged — chunks went elsewhere)
+```
+
+### Step 4: Check where chunks actually went
+```bash
+nx collection info knowledge
+# ACTUAL: Documents: chunks, Index model: voyage-4
+# This bare "knowledge" collection should NOT exist
+```
+
+### Step 5: Verify search cannot find indexed content
+```bash
+# Search for distinctive text from the indexed PDF
+nx search "some unique phrase from the PDF" --corpus knowledge
+# ACTUAL: Returns only pre-existing manual T3 entries, NOT the PDF chunks
+```
+
+## Root Cause (unchanged from original postmortem)
+
+In `nexus/commands/index.py`, the `index_pdf_cmd` function passes the `--collection` argument directly to `doc_indexer.index_pdf()` without calling `t3_collection_name()`:
+
+```python
+# Line ~249 in commands/index.py (v2.4.0)
+n = index_pdf(path, corpus=corpus, collection_name=collection, force=force)
+```
+
+The `collection` variable is the raw user input `"knowledge"`. It should be transformed via:
+
+```python
+from nexus.corpus import t3_collection_name
+collection = t3_collection_name(collection)  # "knowledge" → "knowledge__knowledge"
+```
+
+This same transformation is performed by `store put` (via `commands/store.py`) and `search` (via `corpus.py:resolve_corpus()`), but NOT by `index pdf`.
+
+## Two Bugs From One Missing Call
+
+### Bug 1: Wrong collection name
+- `"knowledge"` is created instead of `"knowledge__knowledge"`
+- `nx search --corpus knowledge` resolves to `knowledge__*` prefix → finds `knowledge__knowledge` → never sees bare `knowledge`
+
+### Bug 2: Wrong embedding model
+- `index_model_for_collection("knowledge")` returns `voyage-4` (default for unknown prefixes)
+- `index_model_for_collection("knowledge__knowledge")` returns `voyage-context-3` (correct for `knowledge__*`)
+- Chunks embedded with `voyage-4` cannot be meaningfully searched with `voyage-context-3` queries
+
+## Required Fix
+
+In `nexus/commands/index.py`, function `index_pdf_cmd`, add before any use of `collection`:
+
+```python
+if collection is not None:
+    from nexus.corpus import t3_collection_name
+    collection = t3_collection_name(collection)
+```
+
+This must be applied in THREE code paths within `index_pdf_cmd`:
+1. Line ~197 (dry-run path): `index_pdf(path, corpus=corpus, t3=local_t3, collection_name=collection, ...)`
+2. Line ~235 (monitor path): `index_pdf(path, corpus=corpus, collection_name=collection, force=force, ...)`
+3. Line ~249 (normal path): `index_pdf(path, corpus=corpus, collection_name=collection, force=force)`
+
+The simplest fix: add the transformation immediately after `path = path.resolve()` (line 181), before any branch:
+
+```python
+path = path.resolve()
+
+# Normalize collection name to T3 convention (e.g. "knowledge" → "knowledge__knowledge")
+if collection is not None:
+    from nexus.corpus import t3_collection_name
+    collection = t3_collection_name(collection)
+```
+
+Similarly check `index md` command (line ~254+) for the same bug.
+
+## Verification After Fix
+
+After applying the fix, re-run the reproduction steps above. Expected results:
+
+1. `nx index pdf test.pdf --collection knowledge` should report "Indexed N chunk(s)."
+2. `nx collection info knowledge__knowledge` should show increased document count
+3. `nx collection info knowledge` should return "not found" or 0 documents
+4. `nx search "phrase from PDF" --corpus knowledge` should return the indexed chunks
+5. The returned chunks should show `embedding_model: voyage-context-3`
+
+## Cleanup Required
+
+After confirming the fix works:
+
+1. Delete the orphaned bare `"knowledge"` collection (18 chunks from failed test):
+```python
+from nexus.db import make_t3
+t3 = make_t3()
+t3.delete_collection('knowledge')
+```
+
+2. Re-index all ART papers (~68 PDFs + CMRB 771 pages) with `--collection knowledge`
+
+3. Verify round-trip search for each major paper
+
+## Workaround (Until Fix Is Applied)
+
+Use the fully-qualified collection name:
+```bash
+nx index pdf /path/to/paper.pdf --collection knowledge__knowledge
+```
+
+This bypasses `t3_collection_name()` entirely (the `__` check in the function returns the input as-is). Both the collection name and embedding model will be correct.

{conexus-2.4.0 → conexus-2.4.2}/docs/rdr/post-mortem/cce-query-model-mismatch.md

@@ -140,28 +140,50 @@ correct; they were mixed with noise from the other corpora.
 
 ---
 
-## Fix (Pending)
+## Fix (Resolved)
 
-Two coordinated changes to `src/nexus/`:
+The original CCE query path fix was deployed in PR #33. RDR-040 (v2.4.0, PR #118)
+then closed the systemic gaps that allowed the bug to ship undetected:
 
-**`corpus.py`** — `embedding_model_for_collection()` returns `"voyage-context-3"`
-for `docs__`, `knowledge__`, and `rdr__` collections.  `index_model_for_collection()`
-likewise corrected for the same three prefixes.
+**Original fix (PR #33):**
 
-**`db/t3.py`** — Two changes:
+- `corpus.py` — `embedding_model_for_collection()` returns `"voyage-context-3"` for CCE collections
+- `db/t3.py` — `search()` and `put()` bypass VoyageAIEmbeddingFunction, call `contextualized_embed()` directly
 
-1. `T3Database.search()` detects CCE collections by checking
-   `index_model_for_collection()` and bypasses `VoyageAIEmbeddingFunction`, calling
-   `vo.contextualized_embed([[query]], model="voyage-context-3", input_type="query")`
-   directly before calling `col.query(query_embeddings=[...])`.
+**RDR-040 gap closure (PR #118, v2.4.0):**
 
-2. `T3Database.put()` also bypasses the voyage-4 EF for CCE collections when
-   `voyage_api_key` is set, calling `_cce_embed(content)` and passing
-   `embeddings=[vec]` to `col.upsert()`.  This ensures single-entry knowledge
-   entries stored via `nx store put` are in the same CCE vector space as
-   multi-chunk doc_indexer entries and are findable by search.
+- **C1**: Single-chunk CCE documents now use `contextualized_embed()` — the `len(chunks) < 2` fallback to voyage-4 was a recurrence of this exact bug class
+- **C4**: Partial CCE batch failure re-embeds entire document consistently — prevents mixed-model vectors
+- **C2/C3**: Paginated all unbounded `col.get()` calls (ChromaDB 300-record hard cap)
+- **C5**: MCP collection cache race eliminated
+- **A1**: Retrieval quality tests assert semantic rank ordering, not just row count
+- **A2**: `verify --deep` uses known-document probe with distance reporting
+- **A3**: Cross-model invariant regression test — fails if CCE index/query models diverge
+- **A4**: `nx collection reindex` command for recovery
+- **B1–B4**: MCP server enhanced with multi-corpus search + collection management tools
 
-All CCE-indexed collections will need re-indexing after the fix is deployed, as the
-existing embeddings are correct — only the query path needs repair.
+## Additional Bug Discovered During Validation
 
-See fix PR (pending).
+A round-trip test of the v2.4.0 release reproduced the *collection naming* variant of
+this failure:
+
+`nx index pdf --collection knowledge` passed the bare name `"knowledge"` directly to
+ChromaDB (bypassing `t3_collection_name()`), creating a collection that `nx search`
+could not find (search uses `resolve_corpus()` which matches `knowledge__*`). Worse,
+`index_model_for_collection("knowledge")` returns `voyage-4` (not CCE), so all chunks
+were embedded with the wrong model — the same cascading failure as the original bug.
+
+**Fix**: PR #119 normalizes `--collection` through `t3_collection_name()` so bare names
+like `"knowledge"` become `"knowledge__knowledge"`.
+
+**Cascading failure chain** (identical pattern to the original):
+```
+--collection knowledge (user input)
+  → Missing t3_collection_name() call
+    → Collection "knowledge" created (wrong name)
+      → index_model_for_collection("knowledge") = voyage-4 (wrong model)
+        → Chunks embedded with voyage-4 (wrong space)
+          → Chunks invisible to search (wrong collection name)
+```
+
+See: `docs/postmortem/2026-03-23-pdf-index-collection-mismatch.md`

{conexus-2.4.0 → conexus-2.4.2}/nx/CHANGELOG.md

@@ -6,6 +6,14 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.4.2] - 2026-03-25
+
+Plugin version aligned with Nexus CLI 2.4.2. No plugin-level functional changes.
+
+## [2.4.1] - 2026-03-24
+
+Plugin version aligned with Nexus CLI 2.4.1. No plugin-level functional changes.
+
 ## [2.4.0] - 2026-03-24
 
 ### Bug Fixes (Track C)

{conexus-2.4.0 → conexus-2.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "conexus"
-version = "2.4.0"
+version = "2.4.2"
 description = "Self-hosted semantic search and knowledge management for LLM-driven development"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12,<3.14"

{conexus-2.4.0 → conexus-2.4.2}/src/nexus/commands/index.py

@@ -150,7 +150,8 @@ def index_repo_cmd(path: Path, frecency_only: bool, force: bool, monitor: bool,
     "--collection",
     default=None,
     help=(
-        "Fully-qualified T3 collection name (e.g. knowledge__delos). "
+        "T3 collection name. Bare names (e.g. 'knowledge') are auto-normalized "
+        "to knowledge__<name>; qualified names (e.g. knowledge__delos) pass through. "
         "Overrides --corpus when set."
     ),
 )
@@ -173,11 +174,18 @@ def index_repo_cmd(path: Path, frecency_only: bool, force: bool, monitor: bool,
               help="Print chunking metadata after indexing. Auto-enabled when stdout is not a TTY.")
 def index_pdf_cmd(path: Path, corpus: str, collection: str | None, dry_run: bool, force: bool, monitor: bool) -> None:
     """Extract and index a PDF document into T3 docs__CORPUS (or --collection)."""
+    from nexus.corpus import t3_collection_name
     from nexus.doc_indexer import index_pdf
 
     if force and dry_run:
         raise click.UsageError("--force and --dry-run are mutually exclusive.")
 
+    # Normalize --collection through t3_collection_name() so bare names like
+    # "knowledge" become "knowledge__knowledge", matching search conventions.
+    # Without this, chunks end up in unsearchable bare collections.
+    if collection is not None:
+        collection = t3_collection_name(collection)
+
     path = path.resolve()
 
     if dry_run:

{conexus-2.4.0 → conexus-2.4.2}/src/nexus/commands/memory.py

@@ -152,11 +152,15 @@ def expire_cmd() -> None:
 
 @memory.command("promote")
 @click.argument("entry_id", metavar="ID", type=int)
-@click.option("--collection", required=True, help="Target T3 collection name (e.g. knowledge__myproject)")
+@click.option("--collection", required=True, help="T3 collection name (e.g. 'knowledge' or 'knowledge__myproject')")
 @click.option("--tags", default="", help="Comma-separated tags (overrides T2 tags when provided)")
 @click.option("--remove", is_flag=True, default=False, help="Delete the entry from T2 after promoting.")
 def promote_cmd(entry_id: int, collection: str, tags: str, remove: bool) -> None:
     """Promote a T2 memory entry to T3 ChromaDB permanent storage."""
+    from nexus.corpus import t3_collection_name
+
+    collection = t3_collection_name(collection)
+
     with T2Database(_default_db_path()) as db:
         entry = db.get(id=entry_id)
         if entry is None:

{conexus-2.4.0 → conexus-2.4.2}/tests/test_index_cmd.py

@@ -468,3 +468,51 @@ def test_md_monitor_return_metadata(runner: CliRunner, index_home: Path) -> None
     assert kwargs.get("return_metadata") is True
     assert "Chunks: 2" in result.output
     assert "Sections: 1" in result.output
+
+
+# ── --collection flag normalization ───────────────────────────────────────────
+
+def test_pdf_collection_flag_normalized_via_t3_collection_name(
+    runner: CliRunner, index_home: Path
+) -> None:
+    """--collection knowledge becomes knowledge__knowledge via t3_collection_name().
+
+    Regression guard: bare collection names like "knowledge" must be normalized
+    to "knowledge__knowledge" so search (which uses resolve_corpus with __
+    prefix matching) can find the indexed chunks.
+    See postmortem: docs/postmortem/2026-03-23-pdf-index-collection-mismatch.md
+    """
+    pdf = index_home / "doc.pdf"
+    pdf.write_bytes(b"fake pdf")
+
+    # Return a dict (monitor path) since CliRunner stdout is non-TTY
+    mock_result = {"chunks": 5, "pages": [1], "title": "T", "author": "A"}
+    with patch("nexus.doc_indexer.index_pdf", return_value=mock_result) as mock_index:
+        result = runner.invoke(
+            main, ["index", "pdf", str(pdf), "--collection", "knowledge"]
+        )
+
+    assert result.exit_code == 0, result.output
+    _, kwargs = mock_index.call_args
+    # Must be normalized: "knowledge" → "knowledge__knowledge"
+    assert kwargs["collection_name"] == "knowledge__knowledge", (
+        f"--collection flag not normalized: got {kwargs['collection_name']!r}"
+    )
+
+
+def test_pdf_collection_flag_already_qualified_unchanged(
+    runner: CliRunner, index_home: Path
+) -> None:
+    """--collection knowledge__delos passes through unchanged."""
+    pdf = index_home / "doc.pdf"
+    pdf.write_bytes(b"fake pdf")
+
+    mock_result = {"chunks": 3, "pages": [1], "title": "T", "author": "A"}
+    with patch("nexus.doc_indexer.index_pdf", return_value=mock_result) as mock_index:
+        result = runner.invoke(
+            main, ["index", "pdf", str(pdf), "--collection", "knowledge__delos"]
+        )
+
+    assert result.exit_code == 0, result.output
+    _, kwargs = mock_index.call_args
+    assert kwargs["collection_name"] == "knowledge__delos"

{conexus-2.4.0 → conexus-2.4.2}/uv.lock

@@ -403,7 +403,7 @@ wheels = [
 
 [[package]]
 name = "conexus"
-version = "2.4.0"
+version = "2.4.2"
 source = { editable = "." }
 dependencies = [
     { name = "chromadb" },