contextual-engine 0.9.5__tar.gz → 0.9.6__tar.gz

{contextual_engine-0.9.5 → contextual_engine-0.9.6}/.gitignore

@@ -21,6 +21,7 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+pytest.ini
 
 # Virtual environments
 .venv/
@@ -106,3 +107,6 @@ output.md
 audit_report.mduv.lock
 audit.md 
 .agent
+.cursor
+.cursor/rules
+.benchmarks

{contextual_engine-0.9.5 → contextual_engine-0.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextual-engine
-Version: 0.9.5
+Version: 0.9.6
 Summary: Temporal-first local code memory for AI tools via MCP
 Project-URL: Homepage, https://contextuallabs.dev
 Project-URL: Documentation, https://contextuallabs.dev/docs
@@ -125,16 +125,19 @@ Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: Other/Proprietary License
 Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Text Processing :: Indexing
 Classifier: Typing :: Typed
-Requires-Python: <3.14,>=3.12
+Requires-Python: <3.15,>=3.11
 Requires-Dist: blake3>=0.4.1
+Requires-Dist: datasketch>=1.6.4
 Requires-Dist: docutils>=0.21
 Requires-Dist: dulwich>=0.21
-Requires-Dist: einops>=0.7
+Requires-Dist: fastembed>=0.4.2
 Requires-Dist: fastmcp<4,>=3.2
 Requires-Dist: httpx[http2]>=0.27.0
 Requires-Dist: huggingface-hub>=0.23
@@ -153,8 +156,7 @@ Requires-Dist: pygit2>=1.15
 Requires-Dist: python-frontmatter
 Requires-Dist: rapidfuzz>=3
 Requires-Dist: rich>=13.0
-Requires-Dist: safetensors>=0.4.3
-Requires-Dist: sentence-transformers>=3.0
+Requires-Dist: setproctitle>=1.3.0
 Requires-Dist: simsimd<6,>=3.9
 Requires-Dist: sqlglot>=20.0
 Requires-Dist: starlette>=0.37
@@ -162,10 +164,7 @@ Requires-Dist: structlog>=25.4
 Requires-Dist: tantivy>=0.20.1
 Requires-Dist: tenacity>=8.0
 Requires-Dist: tiktoken>=0.5
-Requires-Dist: tokenizers<=0.23.0,>=0.19
 Requires-Dist: tomli-w>=1.0.0
-Requires-Dist: torch>=2.2
-Requires-Dist: transformers<4.60,>=4.40
 Requires-Dist: tree-sitter-language-pack>=0.7.2
 Requires-Dist: typer<1.0,>=0.9
 Requires-Dist: uvicorn>=0.27
@@ -178,9 +177,6 @@ Requires-Dist: build>=1.0; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Requires-Dist: twine>=5.0; extra == 'dev'
-Provides-Extra: mps
-Requires-Dist: torch>=2.4.0; extra == 'mps'
-Requires-Dist: torchvision>=0.19.0; extra == 'mps'
 Provides-Extra: test
 Requires-Dist: anyio[trio]>=4.3.0; extra == 'test'
 Requires-Dist: freezegun>=1.5.0; extra == 'test'

{contextual_engine-0.9.5 → contextual_engine-0.9.6}/contextual/cli/commands/doctor.py

@@ -14,7 +14,6 @@ from contextual.config.paths import (
     LOG_DIR,
     MODELS_DIR,
     embed_model_present,
-    rerank_model_present,
     workspace_config,
     workspace_db,
     workspace_logs,
@@ -85,14 +84,10 @@ async def doctor(
     # 3. Models Check — check the actual weight dirs, not MODELS_DIR (which
     # always contains cache/ after setup and would false-positive before fetch).
     embed_ok = embed_model_present()
-    rerank_ok = rerank_model_present()
-    models_ok = embed_ok  # embed is the hard requirement; reranker is search-only
-    if embed_ok and rerank_ok:
-        model_detail = "Embed + reranker weights present."
-    elif embed_ok and not rerank_ok:
-        model_detail = "Embed weights present. Reranker missing — run 'contextual fetch --rerank'."
-    else:
-        model_detail = "Embed weights missing or empty. Run 'contextual fetch'."
+    models_ok = embed_ok
+    model_detail = (
+        "Embed weights present." if embed_ok else "Embed weights missing. Run 'contextual fetch'."
+    )
     checks.append(HealthCheck(name="Models", status=models_ok, detail=model_detail))
 
     # 4. Daemon & Locks Check

contextual_engine-0.9.6/contextual/cli/commands/fetch.py

@@ -0,0 +1,158 @@
+"""Global model fetch command for Contextual.
+
+Downloads the fastembed/ONNX embedding model into ~/.contextual/models/
+(the canonical global model directory) using fastembed's cache_dir parameter.
+After download, computes and stores a BLAKE3 hash pin for integrity verification
+on every subsequent model load.
+
+The old sentence-transformers download path is fully removed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import structlog
+import typer
+
+from contextual.cli.core.decorators import register_command, require_config
+from contextual.cli.core.output import (
+    model_download_progress,
+    print_error,
+    print_fetch_complete,
+    print_fetch_start,
+)
+from contextual.config.paths import GLOBAL_CONFIG, MODELS_DIR, ONNX_PIN_FILE, VERSION_FILE
+from contextual.models.unified_embedder import _FASTEMBED_MODEL, _find_onnx_model_path
+
+_EMBED_FRIENDLY = "Nomic Embed v1.5-Q (ONNX/fastembed)"
+
+
+class FetchError(Exception):
+    """Raised when a global model fetch cannot complete."""
+
+    def __init__(self, message: str, step: str | None = None, recoverable: bool = False) -> None:
+        super().__init__(message)
+        self.step = step
+        self.recoverable = recoverable
+
+
+def _is_fastembed_model_cached() -> bool:
+    """Return True if the ONNX model already exists in ~/.contextual/models/."""
+    onnx_path = _find_onnx_model_path(MODELS_DIR)
+    return onnx_path is not None and onnx_path.exists()
+
+
+def _verify_setup() -> None:
+    from contextual import __version__ as current_version
+
+    if not VERSION_FILE.exists():
+        print_error(
+            "Global setup not found.",
+            hint="Run: contextual setup",
+        )
+        raise typer.Exit(1)
+
+    if not GLOBAL_CONFIG.exists():
+        print_error(
+            "Global config missing.",
+            hint="Run: contextual setup",
+        )
+        raise typer.Exit(1)
+
+    installed = VERSION_FILE.read_text(encoding="utf-8").strip()
+    if installed != current_version:
+        print_error(
+            f"Version mismatch: installed={installed}, current={current_version}.",
+            hint="Run: contextual setup to upgrade.",
+        )
+        raise typer.Exit(1)
+
+
+async def download_embed_model() -> None:
+    """Download the fastembed ONNX model into ~/.contextual/models/ and pin its hash."""
+    logger = structlog.get_logger()
+
+    with model_download_progress(_FASTEMBED_MODEL, size_hint="~130MB"):
+        try:
+            def _load() -> None:
+                from fastembed import TextEmbedding
+                MODELS_DIR.mkdir(parents=True, exist_ok=True)
+                # cache_dir routes fastembed to store weights under ~/.contextual/models/
+                # using HuggingFace Hub directory layout.
+                model = TextEmbedding(
+                    model_name=_FASTEMBED_MODEL,
+                    threads=1,
+                    cache_dir=str(MODELS_DIR),
+                )
+                # One inference pass — verifies the ONNX session loads correctly.
+                list(model.embed(["warmup"], batch_size=1))
+
+            await asyncio.to_thread(_load)
+        except Exception as exc:
+            raise FetchError(
+                f"Failed to download fastembed model: {exc}", step="embed"
+            ) from exc
+
+    # Pin the BLAKE3 hash of the ONNX file so _load_model() can verify integrity
+    # on every subsequent load without re-downloading.
+    try:
+        import blake3 as _blake3
+
+        onnx_path = _find_onnx_model_path(MODELS_DIR)
+        if onnx_path and onnx_path.exists():
+            pin = _blake3.blake3(onnx_path.read_bytes()).hexdigest()
+            ONNX_PIN_FILE.write_text(pin, encoding="utf-8")
+            logger.info(
+                "onnx_pin_written",
+                hash_prefix=pin[:16],
+                onnx_path=str(onnx_path),
+            )
+        else:
+            logger.warning("onnx_pin_skipped", reason="model_file_not_found_after_download")
+    except Exception as exc:
+        logger.warning("onnx_pin_write_failed", error=str(exc))
+
+    logger.info("fastembed_model_ready", model=_FASTEMBED_MODEL, cache_dir=str(MODELS_DIR))
+
+
+@register_command()
+@require_config
+def fetch(
+    embed: bool = typer.Option(False, "--embed", help="Download the Nomic embed model (ONNX)."),
+    all_: bool = typer.Option(False, "--all", help="Download all models (default)."),
+) -> None:
+    """Pre-download fastembed ONNX model weights into ~/.contextual/models/.
+
+    Model is stored in the global Contextual directory alongside the LanceDB
+    index and daemon config. Running this before the first `contextual index`
+    avoids an inline download during indexing and pins the BLAKE3 integrity hash.
+    """
+    _verify_setup()
+
+    print_fetch_start([_EMBED_FRIENDLY])
+
+    downloaded: list[str] = []
+    already_present: list[str] = []
+
+    if _is_fastembed_model_cached():
+        already_present.append(_EMBED_FRIENDLY)
+        # Re-pin even if cached — updates stale or missing pin file.
+        try:
+            import blake3 as _blake3
+
+            onnx_path = _find_onnx_model_path(MODELS_DIR)
+            if onnx_path and onnx_path.exists():
+                pin = _blake3.blake3(onnx_path.read_bytes()).hexdigest()
+                ONNX_PIN_FILE.write_text(pin, encoding="utf-8")
+        except Exception:
+            pass
+    else:
+        try:
+            asyncio.run(download_embed_model())
+            downloaded.append(_EMBED_FRIENDLY)
+        except FetchError as exc:
+            print_error(str(exc), hint="contextual fetch --embed")
+            raise typer.Exit(1) from exc
+
+    print_fetch_complete(downloaded, already_present)

{contextual_engine-0.9.5 → contextual_engine-0.9.6}/contextual/cli/commands/index.py

@@ -95,16 +95,11 @@ async def index(
         try:
             with index_progress() as prog:
                 try:
-                    # Suppress BLAKE3 pin warning during model load — pins are not
-                    # registered until `contextual fetch` is run with a real model.
-                    # The warning fires during SentenceTransformer.__init__, before
-                    # the outer warnings.simplefilter("ignore") wrapper takes effect.
                     warnings.filterwarnings(
                         "ignore",
                         message=".*No BLAKE3 hash pins.*",
                         category=UserWarning,
                     )
-                    # Reranker is search-only — never load at index time (~1.2GB saved).
                     await ensure_models_warm(models=["code", "docs"])
 
                     chunking_started = False

{contextual_engine-0.9.5 → contextual_engine-0.9.6}/contextual/cli/commands/install.py

@@ -103,8 +103,7 @@ def _write_default_config() -> None:
         'tier = "free"\n\n'
         "[models]\n"
         'embed_model = "nomic-ai/nomic-embed-text-v1.5"\n'
-        'rerank_model = "jinaai/jina-reranker-v2-base-multilingual"\n'
-        f'models_dir = "{MODELS_DIR}"\n'
+f'models_dir = "{MODELS_DIR}"\n'
         f'cache_dir = "{MODELS_CACHE_DIR}"\n\n'
         "[storage]\n"
         f'global_db_path = "{GLOBAL_DB_DIR}"\n'

{contextual_engine-0.9.5 → contextual_engine-0.9.6}/contextual/config/__init__.py

@@ -19,7 +19,6 @@ from contextual.config.workspace.retrieval_config import (
     BM25Config,
     DenseConfig,
     MMRConfig,
-    RerankerConfig,
     RetrievalConfig,
 )
 from contextual.config.workspace.workspace_config import WorkspaceConfig
@@ -109,7 +108,6 @@ __all__ = [
     "MMRConfig",
     "ObservabilityConfig",
     "PipelineConfig",
-    "RerankerConfig",
     "RetrievalConfig",
     "SecurityConfig",
     "StorageConfig",

{contextual_engine-0.9.5 → contextual_engine-0.9.6}/contextual/config/base.py

@@ -25,7 +25,7 @@ class ContextualConfig(BaseModel):
         project_root: Absolute path to the project being indexed.
         indexing: Indexing configuration for code and workspace files.
         embedding: Embedding model configuration.
-        retrieval: Retrieval configuration for search and reranking.
+        retrieval: Retrieval configuration for search (RRF fusion + MMR).
         storage: Storage configuration for database and index paths.
         security: Security configuration for filesystem and workspace policy.
     """

{contextual_engine-0.9.5 → contextual_engine-0.9.6}/contextual/config/global_/mcp_config.py

@@ -34,10 +34,16 @@ class DaemonConfig(BaseModel):
     port: int = 9091                   # must match _platform.WINDOWS_PORT/TCP_PORT
 
     # Lifecycle
-    idle_sleep_minutes: int = 30       # Minutes idle before daemon sleeps (releases RAM)
-    die_after_sleep_hours: float = 2.0 # Hours asleep before daemon fully exits (0 = never)
-    startup_timeout: float = 45.0      # Seconds to wait for the daemon to start serving
-                                       # (model load is 20-50s on 8GB unified memory)
+    # idle_sleep_minutes: minutes of no incoming MCP requests before the daemon
+    # unloads the ONNX model and enters sleep state. Active shim connections
+    # (idle SSE sessions) do NOT prevent this — only actual HTTP requests reset
+    # the clock.  die_after_sleep_hours: hours asleep before a clean SIGTERM
+    # exit. Total inactivity before full exit = idle_sleep_minutes +
+    # die_after_sleep_hours * 60.  Set die_after_sleep_hours = 0 to never exit.
+    idle_sleep_minutes: int = 30       # Minutes of no requests before sleeping
+    die_after_sleep_hours: float = 1.0 # Hours asleep before clean exit (0 = never)
+    startup_timeout: float = 15.0      # Seconds to wait for the daemon to start serving
+                                       # (ONNX model loads in ~2-5s from ~/.contextual/models/)
 
     # Rate limiting
     rate_limit_per_minute: int = 120   # Max tool calls per minute per client
@@ -53,11 +59,13 @@ class DaemonConfig(BaseModel):
     # Heap / memory trimmer
     # When the daemon's physical footprint exceeds heap_trim_threshold_mb a
     # hard trim fires (GC + malloc page return). If the footprint is still over
-    # the threshold on the next tick and no sessions are active, models are
-    # offloaded to CPU to recover MPS/GPU pages. Set to 0 to disable.
+    # the threshold on the next tick and no sessions are active, the ONNX model
+    # session is unloaded (freed from memory). Set to 0 to disable.
+    # 1500 MB accounts for: ONNX session (~130 MB) + LanceDB PyArrow buffers
+    # (~400-800 MB active) + graph/cache overhead — triggers before OOM pressure.
     heap_monitor_enabled: bool = True
     heap_monitor_interval_seconds: int = 30
-    heap_trim_threshold_mb: int = 2500
+    heap_trim_threshold_mb: int = 1500
 
     # Logging
     log_level: str = "INFO"

{contextual_engine-0.9.5 → contextual_engine-0.9.6}/contextual/config/indexing.py

@@ -38,12 +38,11 @@ def resolve_local_model_path(model_ref: str) -> Path:
 
 
 class EmbeddingConfig(BaseModel):
-    """Embedding model configuration (ADR-005: sentence-transformers unified stack)."""
+    """Embedding model configuration (nomic-embed-text-v1.5 via fastembed/ONNX Runtime since v0.10)."""
 
     # Production models — all Apache-2.0 licensed, all 768d
     code_model: str = Field(default=str(MODEL_CACHE_DIR / "nomic-embed-text-v1.5"))
     docs_model: str = Field(default=str(MODEL_CACHE_DIR / "nomic-embed-text-v1.5"))
-    reranker_model: str = Field(default=str(MODEL_CACHE_DIR / "jina-reranker-v2-base-multilingual"))
     dimension: int = Field(default=768)
     batch_size: int = Field(default=16)  # conservative default for 8GB unified memory Macs
     max_context_length: int = Field(default=8192)
@@ -90,49 +89,17 @@ class IndexingConfig(BaseModel):
     debounce_ms: int = Field(default=500)  # file watcher debounce
 
 
-class RerankerConfig(BaseModel):
-    """Reranker service settings (BGE cross-encoder via sentence-transformers)."""
-
-    top_k: int = Field(default=15)
-    max_candidate_length: int = Field(default=2000)
-    batch_size: int = Field(default=15)
-    timeout_seconds: float = Field(default=10.0)
-    enable_retry: bool = Field(default=True)
-    fallback_on_error: bool = Field(default=True)
-
-
 class SearchConfig(BaseModel):
-    """Search pipeline settings (RRF + reranker + MMR)."""
+    """Search pipeline settings (RRF + MMR)."""
 
     rrf_k: int = Field(default=60)
     bm25_weight: float = Field(default=0.4)
     dense_weight: float = Field(default=0.6)
-    rrf_candidate_pool: int = Field(
-        default=35,
-        ge=10,
-        le=200,
-        description="Number of candidates retrieved before reranking.",
-    )
-    enable_reranker: bool = Field(default=False)  # 124x latency overhead with no accuracy gain on MPS
-    rerank_top_k: int = Field(
-        default=10,
-        ge=5,
-        le=100,
-        description="Number of candidates passed to cross-encoder.",
-    )
+    rrf_candidate_pool: int = Field(default=35, ge=10, le=200)
     mmr_lambda: float = Field(default=0.7)
     mmr_max_per_file: int = Field(default=2)
     mmr_max_per_symbol: int = Field(default=1)
 
-    @model_validator(mode="after")
-    def validate_pool_sizes(self) -> SearchConfig:
-        if self.rerank_top_k > self.rrf_candidate_pool:
-            raise ValueError(
-                f"rerank_top_k ({self.rerank_top_k}) cannot exceed "
-                f"rrf_candidate_pool ({self.rrf_candidate_pool})"
-            )
-        return self
-
 
 class CacheConfig(BaseModel):
     """Embedding cache settings."""
@@ -150,11 +117,9 @@ class RetrievalConfig:
     dense_candidates: int = 100
     rrf_candidates: int = 50
     rrf_k: int = 60
-    rrf_dense_weight: float = 0.6
-    rrf_bm25_weight: float = 0.4
-    reranker_enabled: bool = False  # 124x latency overhead with no accuracy gain on MPS
-    reranker_top_n: int = 15
-    reranker_max_chunk_chars: int = 2000
+    rrf_dense_weight: float = 0.50
+    rrf_bm25_weight: float = 0.35
+    rrf_trigram_weight: float = 0.15
     mmr_enabled: bool = True
     mmr_lambda: float = 0.7
     mmr_max_chunks_per_file: int = 2
@@ -168,6 +133,10 @@ class RetrievalConfig:
     # distances. 10-20 recovers near-flat recall at a few ms cost.
     refine_factor: int = 20
     query_cache_ttl_seconds: int = 300
+    # Row count at which the incremental indexer triggers background IVF-PQ
+    # index maintenance.  Below this threshold flat-scan ANN is fast enough
+    # and building IVF-PQ would waste CPU.  Set to 0 to disable.
+    ann_index_row_threshold: int = 50_000
 
     @classmethod
     def from_toml(cls, config_path: Path) -> RetrievalConfig:
@@ -200,12 +169,8 @@ class RetrievalConfig:
             rrf_bm25_weight=float(
                 retrieval_data.get("rrf_bm25_weight", defaults.rrf_bm25_weight)
             ),
-            reranker_enabled=bool(
-                retrieval_data.get("reranker_enabled", defaults.reranker_enabled)
-            ),
-            reranker_top_n=int(retrieval_data.get("reranker_top_n", defaults.reranker_top_n)),
-            reranker_max_chunk_chars=int(
-                retrieval_data.get("reranker_max_chunk_chars", defaults.reranker_max_chunk_chars)
+            rrf_trigram_weight=float(
+                retrieval_data.get("rrf_trigram_weight", defaults.rrf_trigram_weight)
             ),
             mmr_enabled=bool(retrieval_data.get("mmr_enabled", defaults.mmr_enabled)),
             mmr_lambda=float(retrieval_data.get("mmr_lambda", defaults.mmr_lambda)),
@@ -224,6 +189,9 @@ class RetrievalConfig:
             query_cache_ttl_seconds=int(
                 retrieval_data.get("query_cache_ttl_seconds", defaults.query_cache_ttl_seconds)
             ),
+            ann_index_row_threshold=int(
+                retrieval_data.get("ann_index_row_threshold", defaults.ann_index_row_threshold)
+            ),
         )
 
 
@@ -233,7 +201,6 @@ class PipelineConfig(BaseModel):
     embedding: EmbeddingConfig = Field(default_factory=EmbeddingConfig)
     chunking: ChunkingConfig = Field(default_factory=ChunkingConfig)
     indexing: IndexingConfig = Field(default_factory=IndexingConfig)
-    reranker: RerankerConfig = Field(default_factory=RerankerConfig)
     search: SearchConfig = Field(default_factory=SearchConfig)
     cache: CacheConfig = Field(default_factory=CacheConfig)
 
@@ -247,8 +214,6 @@ class PipelineConfig(BaseModel):
             cfg.embedding.code_model = v
         if v := os.getenv("CONTEXTUAL_DOCS_MODEL"):
             cfg.embedding.docs_model = v
-        if v := os.getenv("CONTEXTUAL_RERANKER_MODEL"):
-            cfg.embedding.reranker_model = v
         if v := os.getenv("CONTEXTUAL_EMBED_DIM"):
             cfg.embedding.dimension = int(v)
         if v := os.getenv("CONTEXTUAL_EMBED_BATCH_SIZE"):
@@ -258,7 +223,6 @@ class PipelineConfig(BaseModel):
 
         cfg.embedding.code_model = str(resolve_local_model_path(cfg.embedding.code_model))
         cfg.embedding.docs_model = str(resolve_local_model_path(cfg.embedding.docs_model))
-        cfg.embedding.reranker_model = str(resolve_local_model_path(cfg.embedding.reranker_model))
 
         # Indexing overrides
         if v := os.getenv("CONTEXTUAL_BATCH_WRITE_SIZE"):
@@ -315,8 +279,6 @@ class RuntimeRetrievalConfig:
     rrf_k: int = 60
     rrf_dense_weight: float = 0.6
     rrf_bm25_weight: float = 0.4
-    reranker_enabled: bool = False  # 124x latency overhead with no accuracy gain on MPS
-    reranker_top_n: int = 15
     mmr_lambda: float = 0.7
     mmr_max_chunks_per_file: int = 2
     mmr_max_chunks_per_symbol: int = 1
@@ -390,8 +352,6 @@ class ConfigLoader:
                 "rrf_k": 60,
                 "rrf_dense_weight": 0.6,
                 "rrf_bm25_weight": 0.4,
-                "reranker_enabled": False,  # 124x latency overhead with no accuracy gain on MPS
-                "reranker_top_n": 15,
                 "mmr_lambda": 0.7,
                 "mmr_max_chunks_per_file": 2,
                 "mmr_max_chunks_per_symbol": 1,
@@ -435,8 +395,6 @@ class ConfigLoader:
             env_overrides["retrieval"]["rrf_dense_weight"] = float(value)
         if value := os.getenv("CONTEXTUAL_RRF_BM25_WEIGHT"):
             env_overrides["retrieval"]["rrf_bm25_weight"] = float(value)
-        if value := os.getenv("CONTEXTUAL_RERANKER_TOP_N"):
-            env_overrides["retrieval"]["reranker_top_n"] = int(value)
         if value := os.getenv("CONTEXTUAL_MMR_LAMBDA"):
             env_overrides["retrieval"]["mmr_lambda"] = float(value)
         if value := os.getenv("CONTEXTUAL_MMR_MAX_CHUNKS_PER_FILE"):

{contextual_engine-0.9.5 → contextual_engine-0.9.6}/contextual/config/paths.py

@@ -46,12 +46,13 @@ MCP_CONFIG_FILE = CONTEXTUAL_HOME / "mcp.json"
 WORKSPACES_JSON_PATH = CONTEXTUAL_HOME / "workspaces.json"
 LOG_DIR = Path.home() / ".local" / "state" / "contextual" / "logs"
 
-# Canonical per-model weight directories. `contextual fetch` downloads into
-# these exact paths. Readiness checks MUST look here, not at MODELS_DIR — the
-# latter always contains `cache/` after `setup`, so a bare MODELS_DIR.iterdir()
-# is non-empty even when no weights have been fetched (false positive).
-EMBED_MODEL_DIR = MODELS_DIR / "nomic-embed-text-v1.5"
-RERANK_MODEL_DIR = MODELS_DIR / "jina-reranker-v2-base-multilingual"
+# fastembed Hub cache directory for the embed model.
+# `contextual fetch` downloads into MODELS_DIR using fastembed's cache_dir
+# parameter; fastembed mirrors HuggingFace Hub layout under that root.
+EMBED_MODEL_DIR = MODELS_DIR / "models--nomic-ai--nomic-embed-text-v1.5"
+
+# BLAKE3 hash pin file written by `contextual fetch` and verified on model load.
+ONNX_PIN_FILE = MODELS_DIR / ".onnx_pin"
 
 
 def _dir_has_content(path: Path) -> bool:
@@ -62,17 +63,17 @@ def _dir_has_content(path: Path) -> bool:
 
 
 def embed_model_present() -> bool:
-    """True when the embed model weights have been fetched.
-
-    Embed weights are the hard requirement for indexing (the reranker is
-    search-only), so this is the canonical "models ready enough to index" gate.
-    """
-    return _dir_has_content(EMBED_MODEL_DIR)
-
-
-def rerank_model_present() -> bool:
-    """True when the reranker weights have been fetched."""
-    return _dir_has_content(RERANK_MODEL_DIR)
+    """True when the ONNX embed model has been fetched into ~/.contextual/models/."""
+    if not _dir_has_content(EMBED_MODEL_DIR):
+        return False
+    snapshots = EMBED_MODEL_DIR / "snapshots"
+    if not snapshots.is_dir():
+        return False
+    return any(
+        (s / "onnx" / "model_quantized.onnx").exists()
+        for s in snapshots.iterdir()
+        if s.is_dir()
+    )
 
 
 # ── Workspace subdirectories ──────────

{contextual_engine-0.9.5 → contextual_engine-0.9.6}/contextual/config/workspace/__init__.py

@@ -5,7 +5,6 @@ from contextual.config.workspace.retrieval_config import (
     BM25Config,
     DenseConfig,
     MMRConfig,
-    RerankerConfig,
     RetrievalConfig,
     RRFConfig,
 )
@@ -20,7 +19,6 @@ __all__ = [
     "MMRConfig",
     "ObservabilityConfig",
     "RRFConfig",
-    "RerankerConfig",
     "RetrievalConfig",
     "WorkspaceConfig",
 ]

{contextual_engine-0.9.5 → contextual_engine-0.9.6}/contextual/config/workspace/retrieval_config.py

@@ -24,13 +24,6 @@ class RRFConfig(BaseModel):
     bm25_weight: float = 0.4
 
 
-class RerankerConfig(BaseModel):
-    """Cross-encoder reranking settings."""
-
-    top_n: int = 15
-    max_chunk_chars: int = 2000
-
-
 class MMRConfig(BaseModel):
     """MMR diversity settings."""
 
@@ -45,7 +38,6 @@ class RetrievalConfig(BaseModel):
     bm25: BM25Config = BM25Config()
     dense: DenseConfig = DenseConfig()
     rrf: RRFConfig = RRFConfig()
-    reranker: RerankerConfig = RerankerConfig()
     mmr: MMRConfig = MMRConfig()
     final_top_k: int = 10
     max_context_tokens: int = 8000

{contextual_engine-0.9.5 → contextual_engine-0.9.6}/contextual/core/errors.py

@@ -138,7 +138,6 @@ class ErrorCode(StrEnum):
     RETRIEVAL_BM25_FAILED = "retrieval_bm25_failed"
     RETRIEVAL_DENSE_SEARCH_FAILED = "retrieval_dense_search_failed"
     RETRIEVAL_FUSION_FAILED = "retrieval_fusion_failed"
-    RETRIEVAL_RERANK_FAILED = "retrieval_rerank_failed"
     RETRIEVAL_HYDRATION_FAILED = "retrieval_hydration_failed"
     RETRIEVAL_NO_RESULTS = "retrieval_no_results"  # Not an error, informational
 
@@ -315,7 +314,7 @@ class GitError(ContextualExceptionError):
 
 
 class RetrievalError(ContextualExceptionError):
-    """Errors from the retrieval pipeline (search, fusion, reranking)."""
+    """Errors from the retrieval pipeline (search, RRF fusion, MMR)."""
 
 
 class SecurityError(ContextualExceptionError):