vexor 0.19.0__py3-none-any.whl → 0.20.0__py3-none-any.whl

vexor/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from .api import VexorError, clear_index, index, search
+from .api import VexorError, clear_index, index, search, set_config_json, set_data_dir
 
 __all__ = [
     "__version__",
@@ -11,9 +11,11 @@ __all__ = [
     "get_version",
     "index",
     "search",
+    "set_config_json",
+    "set_data_dir",
 ]
 
-__version__ = "0.19.0"
+__version__ = "0.20.0"
 
 
 def get_version() -> str:

vexor/_bundled_skills/vexor-cli/SKILL.md

@@ -31,6 +31,7 @@ vexor "<QUERY>" [--path <ROOT>] [--mode <MODE>] [--ext .py,.md] [--exclude-patte
 - `--no-respect-gitignore`: include ignored files
 - `--no-recursive`: only the top directory
 - `--format`: `rich` (default) or `porcelain`/`porcelain-z` for scripts
+- `--no-cache`: in-memory only, do not read/write index cache
 
 ## Modes (pick the cheapest that works)
 

vexor/api.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path
+from collections.abc import Mapping
 from typing import Sequence
 
 from .config import (
@@ -13,9 +14,12 @@ from .config import (
     Config,
     RemoteRerankConfig,
     SUPPORTED_RERANKERS,
+    config_from_json,
     load_config,
     resolve_default_model,
+    set_config_dir,
 )
+from .cache import set_cache_dir
 from .modes import available_modes, get_strategy
 from .services.index_service import IndexResult, build_index, clear_index_entries
 from .services.search_service import SearchRequest, SearchResponse, perform_search
@@ -47,6 +51,30 @@ class RuntimeSettings:
     remote_rerank: RemoteRerankConfig | None
 
 
+_RUNTIME_CONFIG: Config | None = None
+
+
+def set_data_dir(path: Path | str | None) -> None:
+    """Set the base directory for config and cache data."""
+    set_config_dir(path)
+    set_cache_dir(path)
+
+
+def set_config_json(
+    payload: Mapping[str, object] | str | None, *, replace: bool = False
+) -> None:
+    """Set in-memory config for API calls from a JSON string or mapping."""
+    global _RUNTIME_CONFIG
+    if payload is None:
+        _RUNTIME_CONFIG = None
+        return
+    base = None if replace else (_RUNTIME_CONFIG or load_config())
+    try:
+        _RUNTIME_CONFIG = config_from_json(payload, base=base)
+    except ValueError as exc:
+        raise VexorError(str(exc)) from exc
+
+
 def search(
     query: str,
     *,
@@ -67,6 +95,9 @@ def search(
     local_cuda: bool | None = None,
     auto_index: bool | None = None,
     use_config: bool = True,
+    config: Config | Mapping[str, object] | str | None = None,
+    temporary_index: bool = False,
+    no_cache: bool = False,
 ) -> SearchResponse:
     """Run a semantic search and return ranked results."""
 
@@ -95,6 +126,8 @@ def search(
         local_cuda=local_cuda,
         auto_index=auto_index,
         use_config=use_config,
+        runtime_config=_RUNTIME_CONFIG,
+        config_override=config,
     )
 
     request = SearchRequest(
@@ -115,6 +148,8 @@ def search(
         exclude_patterns=normalized_excludes,
         extensions=normalized_exts,
         auto_index=settings.auto_index,
+        temporary_index=temporary_index,
+        no_cache=no_cache,
         rerank=settings.rerank,
         flashrank_model=settings.flashrank_model,
         remote_rerank=settings.remote_rerank,
@@ -139,6 +174,7 @@ def index(
     api_key: str | None = None,
     local_cuda: bool | None = None,
     use_config: bool = True,
+    config: Config | Mapping[str, object] | str | None = None,
 ) -> IndexResult:
     """Build or refresh the index for the given directory."""
 
@@ -159,6 +195,8 @@ def index(
         local_cuda=local_cuda,
         auto_index=None,
         use_config=use_config,
+        runtime_config=_RUNTIME_CONFIG,
+        config_override=config,
     )
 
     return build_index(
@@ -220,6 +258,8 @@ def _validate_mode(mode: str) -> str:
     return mode
 
 
+
+
 def _normalize_extensions(values: Sequence[str] | str | None) -> tuple[str, ...]:
     return normalize_extensions(_coerce_iterable(values))
 
@@ -247,8 +287,16 @@ def _resolve_settings(
     local_cuda: bool | None,
     auto_index: bool | None,
     use_config: bool,
+    runtime_config: Config | None = None,
+    config_override: Config | Mapping[str, object] | str | None = None,
 ) -> RuntimeSettings:
-    config = load_config() if use_config else Config()
+    config = (
+        runtime_config if (use_config and runtime_config is not None) else None
+    )
+    if config is None:
+        config = load_config() if use_config else Config()
+    if config_override is not None:
+        config = _apply_config_override(config, config_override)
     provider_value = (provider or config.provider or DEFAULT_PROVIDER).lower()
     rerank_value = (config.rerank or DEFAULT_RERANK).strip().lower()
     if rerank_value not in SUPPORTED_RERANKERS:
@@ -278,3 +326,15 @@ def _resolve_settings(
         flashrank_model=config.flashrank_model,
         remote_rerank=config.remote_rerank,
     )
+
+
+def _apply_config_override(
+    base: Config,
+    override: Config | Mapping[str, object] | str,
+) -> Config:
+    if isinstance(override, Config):
+        return override
+    try:
+        return config_from_json(override, base=base)
+    except ValueError as exc:
+        raise VexorError(str(exc)) from exc

vexor/cache.py

@@ -14,7 +14,8 @@ import numpy as np
 
 from .utils import collect_files
 
-CACHE_DIR = Path(os.path.expanduser("~")) / ".vexor"
+DEFAULT_CACHE_DIR = Path(os.path.expanduser("~")) / ".vexor"
+CACHE_DIR = DEFAULT_CACHE_DIR
 CACHE_VERSION = 5
 DB_FILENAME = "index.db"
 EMBED_CACHE_TTL_DAYS = 30
@@ -119,6 +120,17 @@ def ensure_cache_dir() -> Path:
     return CACHE_DIR
 
 
+def set_cache_dir(path: Path | str | None) -> None:
+    global CACHE_DIR
+    if path is None:
+        CACHE_DIR = DEFAULT_CACHE_DIR
+        return
+    dir_path = Path(path).expanduser().resolve()
+    if dir_path.exists() and not dir_path.is_dir():
+        raise NotADirectoryError(f"Path is not a directory: {dir_path}")
+    CACHE_DIR = dir_path
+
+
 def cache_db_path() -> Path:
     """Return the absolute path to the shared SQLite cache database."""
 

vexor/cli.py

@@ -389,6 +389,11 @@ def search(
         "--format",
         help=Messages.HELP_SEARCH_FORMAT,
     ),
+    no_cache: bool = typer.Option(
+        False,
+        "--no-cache",
+        help=Messages.HELP_NO_CACHE,
+    ),
 ) -> None:
     """Run the semantic search."""
     config = load_config()
@@ -440,20 +445,35 @@ def search(
         exclude_patterns=normalized_excludes,
         extensions=normalized_exts,
         auto_index=auto_index,
+        no_cache=no_cache,
         rerank=rerank,
         flashrank_model=flashrank_model,
         remote_rerank=remote_rerank,
     )
     if output_format == SearchOutputFormat.rich:
-        should_index_first = _should_index_before_search(request) if auto_index else False
-        if should_index_first:
+        if no_cache:
             console.print(
-                _styled(Messages.INFO_INDEX_RUNNING.format(path=directory), Styles.INFO)
+                _styled(
+                    Messages.INFO_SEARCH_RUNNING_NO_CACHE.format(path=directory),
+                    Styles.INFO,
+                )
             )
         else:
-            console.print(
-                _styled(Messages.INFO_SEARCH_RUNNING.format(path=directory), Styles.INFO)
+            should_index_first = (
+                _should_index_before_search(request) if auto_index else False
             )
+            if should_index_first:
+                console.print(
+                    _styled(
+                        Messages.INFO_INDEX_RUNNING.format(path=directory), Styles.INFO
+                    )
+                )
+            else:
+                console.print(
+                    _styled(
+                        Messages.INFO_SEARCH_RUNNING.format(path=directory), Styles.INFO
+                    )
+                )
     try:
         response = perform_search(request)
     except FileNotFoundError:

vexor/config.py

@@ -5,11 +5,15 @@ from __future__ import annotations
 import json
 import os
 from dataclasses import dataclass
+from collections.abc import Mapping
 from pathlib import Path
 from typing import Any, Dict
 from urllib.parse import urlparse, urlunparse
 
-CONFIG_DIR = Path(os.path.expanduser("~")) / ".vexor"
+from .text import Messages
+
+DEFAULT_CONFIG_DIR = Path(os.path.expanduser("~")) / ".vexor"
+CONFIG_DIR = DEFAULT_CONFIG_DIR
 CONFIG_FILE = CONFIG_DIR / "config.json"
 DEFAULT_MODEL = "text-embedding-3-small"
 DEFAULT_GEMINI_MODEL = "gemini-embedding-001"
@@ -129,6 +133,38 @@ def flashrank_cache_dir(*, create: bool = True) -> Path:
     return cache_dir
 
 
+def set_config_dir(path: Path | str | None) -> None:
+    global CONFIG_DIR, CONFIG_FILE
+    if path is None:
+        CONFIG_DIR = DEFAULT_CONFIG_DIR
+    else:
+        dir_path = Path(path).expanduser().resolve()
+        if dir_path.exists() and not dir_path.is_dir():
+            raise NotADirectoryError(f"Path is not a directory: {dir_path}")
+        CONFIG_DIR = dir_path
+    CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+def config_from_json(
+    payload: str | Mapping[str, object], *, base: Config | None = None
+) -> Config:
+    """Return a Config from a JSON string or mapping without saving it."""
+    data = _coerce_config_payload(payload)
+    config = Config() if base is None else _clone_config(base)
+    _apply_config_payload(config, data)
+    return config
+
+
+def update_config_from_json(
+    payload: str | Mapping[str, object], *, replace: bool = False
+) -> Config:
+    """Update config from a JSON string or mapping and persist it."""
+    base = None if replace else load_config()
+    config = config_from_json(payload, base=base)
+    save_config(config)
+    return config
+
+
 def set_api_key(value: str | None) -> None:
     config = load_config()
     config.api_key = value
@@ -281,3 +317,152 @@ def resolve_remote_rerank_api_key(configured: str | None) -> str | None:
     if env_key:
         return env_key
     return None
+
+
+def _coerce_config_payload(payload: str | Mapping[str, object]) -> Mapping[str, object]:
+    if isinstance(payload, str):
+        try:
+            data = json.loads(payload)
+        except json.JSONDecodeError as exc:
+            raise ValueError(Messages.ERROR_CONFIG_JSON_INVALID) from exc
+    elif isinstance(payload, Mapping):
+        data = dict(payload)
+    else:
+        raise ValueError(Messages.ERROR_CONFIG_JSON_INVALID)
+    if not isinstance(data, Mapping):
+        raise ValueError(Messages.ERROR_CONFIG_JSON_INVALID)
+    return data
+
+
+def _clone_config(config: Config) -> Config:
+    remote = config.remote_rerank
+    return Config(
+        api_key=config.api_key,
+        model=config.model,
+        batch_size=config.batch_size,
+        embed_concurrency=config.embed_concurrency,
+        provider=config.provider,
+        base_url=config.base_url,
+        auto_index=config.auto_index,
+        local_cuda=config.local_cuda,
+        rerank=config.rerank,
+        flashrank_model=config.flashrank_model,
+        remote_rerank=(
+            None
+            if remote is None
+            else RemoteRerankConfig(
+                base_url=remote.base_url,
+                api_key=remote.api_key,
+                model=remote.model,
+            )
+        ),
+    )
+
+
+def _apply_config_payload(config: Config, payload: Mapping[str, object]) -> None:
+    if "api_key" in payload:
+        config.api_key = _coerce_optional_str(payload["api_key"], "api_key")
+    if "model" in payload:
+        config.model = _coerce_required_str(payload["model"], "model", DEFAULT_MODEL)
+    if "batch_size" in payload:
+        config.batch_size = _coerce_int(
+            payload["batch_size"], "batch_size", DEFAULT_BATCH_SIZE
+        )
+    if "embed_concurrency" in payload:
+        config.embed_concurrency = _coerce_int(
+            payload["embed_concurrency"],
+            "embed_concurrency",
+            DEFAULT_EMBED_CONCURRENCY,
+        )
+    if "provider" in payload:
+        config.provider = _coerce_required_str(
+            payload["provider"], "provider", DEFAULT_PROVIDER
+        )
+    if "base_url" in payload:
+        config.base_url = _coerce_optional_str(payload["base_url"], "base_url")
+    if "auto_index" in payload:
+        config.auto_index = _coerce_bool(payload["auto_index"], "auto_index")
+    if "local_cuda" in payload:
+        config.local_cuda = _coerce_bool(payload["local_cuda"], "local_cuda")
+    if "rerank" in payload:
+        config.rerank = _normalize_rerank(payload["rerank"])
+    if "flashrank_model" in payload:
+        config.flashrank_model = _coerce_optional_str(
+            payload["flashrank_model"], "flashrank_model"
+        )
+    if "remote_rerank" in payload:
+        config.remote_rerank = _coerce_remote_rerank(payload["remote_rerank"])
+
+
+def _coerce_optional_str(value: object, field: str) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        cleaned = value.strip()
+        return cleaned or None
+    raise ValueError(Messages.ERROR_CONFIG_VALUE_INVALID.format(field=field))
+
+
+def _coerce_required_str(value: object, field: str, default: str) -> str:
+    if value is None:
+        return default
+    if isinstance(value, str):
+        cleaned = value.strip()
+        return cleaned or default
+    raise ValueError(Messages.ERROR_CONFIG_VALUE_INVALID.format(field=field))
+
+
+def _coerce_int(value: object, field: str, default: int) -> int:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        raise ValueError(Messages.ERROR_CONFIG_VALUE_INVALID.format(field=field))
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        if value.is_integer():
+            return int(value)
+        raise ValueError(Messages.ERROR_CONFIG_VALUE_INVALID.format(field=field))
+    if isinstance(value, str):
+        cleaned = value.strip()
+        if not cleaned:
+            return default
+        try:
+            return int(cleaned)
+        except ValueError as exc:
+            raise ValueError(Messages.ERROR_CONFIG_VALUE_INVALID.format(field=field)) from exc
+    raise ValueError(Messages.ERROR_CONFIG_VALUE_INVALID.format(field=field))
+
+
+def _coerce_bool(value: object, field: str) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int) and value in (0, 1):
+        return bool(value)
+    if isinstance(value, str):
+        cleaned = value.strip().lower()
+        if cleaned in {"true", "1", "yes", "on"}:
+            return True
+        if cleaned in {"false", "0", "no", "off"}:
+            return False
+    raise ValueError(Messages.ERROR_CONFIG_VALUE_INVALID.format(field=field))
+
+
+def _normalize_rerank(value: object) -> str:
+    if value is None:
+        normalized = DEFAULT_RERANK
+    elif isinstance(value, str):
+        normalized = value.strip().lower() or DEFAULT_RERANK
+    else:
+        raise ValueError(Messages.ERROR_CONFIG_VALUE_INVALID.format(field="rerank"))
+    if normalized not in SUPPORTED_RERANKERS:
+        normalized = DEFAULT_RERANK
+    return normalized
+
+
+def _coerce_remote_rerank(value: object) -> RemoteRerankConfig | None:
+    if value is None:
+        return None
+    if isinstance(value, Mapping):
+        return _parse_remote_rerank(dict(value))
+    raise ValueError(Messages.ERROR_CONFIG_VALUE_INVALID.format(field="remote_rerank"))

vexor/services/index_service.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import os
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from enum import Enum
 from pathlib import Path
 from typing import MutableMapping, Sequence
@@ -51,6 +52,7 @@ def build_index(
     local_cuda: bool = False,
     exclude_patterns: Sequence[str] | None = None,
     extensions: Sequence[str] | None = None,
+    no_cache: bool = False,
 ) -> IndexResult:
     """Create or refresh the cached index for *directory*."""
 
@@ -187,6 +189,7 @@ def build_index(
                 exclude_patterns=exclude_patterns,
                 extensions=extensions,
                 stat_cache=stat_cache,
+                no_cache=no_cache,
             )
 
             line_backfill_targets = missing_line_files - changed_rel_paths - removed_rel_paths
@@ -220,6 +223,7 @@ def build_index(
         searcher=searcher,
         model_name=model_name,
         labels=file_labels,
+        no_cache=no_cache,
     )
     entries = _build_index_entries(payloads, embeddings, directory, stat_cache=stat_cache)
 
@@ -241,6 +245,150 @@ def build_index(
     )
 
 
+def build_index_in_memory(
+    directory: Path,
+    *,
+    include_hidden: bool,
+    respect_gitignore: bool = True,
+    mode: str,
+    recursive: bool,
+    model_name: str,
+    batch_size: int,
+    embed_concurrency: int = DEFAULT_EMBED_CONCURRENCY,
+    provider: str,
+    base_url: str | None,
+    api_key: str | None,
+    local_cuda: bool = False,
+    exclude_patterns: Sequence[str] | None = None,
+    extensions: Sequence[str] | None = None,
+    no_cache: bool = False,
+) -> tuple[list[Path], np.ndarray, dict]:
+    """Build an index in memory without writing to disk."""
+
+    from ..search import VexorSearcher  # local import
+    from ..utils import collect_files  # local import
+
+    files = collect_files(
+        directory,
+        include_hidden=include_hidden,
+        recursive=recursive,
+        extensions=extensions,
+        exclude_patterns=exclude_patterns,
+        respect_gitignore=respect_gitignore,
+    )
+    if not files:
+        empty = np.empty((0, 0), dtype=np.float32)
+        metadata = {
+            "index_id": None,
+            "version": CACHE_VERSION,
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+            "root": str(directory),
+            "model": model_name,
+            "include_hidden": include_hidden,
+            "respect_gitignore": respect_gitignore,
+            "recursive": recursive,
+            "mode": mode,
+            "dimension": 0,
+            "exclude_patterns": tuple(exclude_patterns or ()),
+            "extensions": tuple(extensions or ()),
+            "files": [],
+            "chunks": [],
+        }
+        return [], empty, metadata
+
+    stat_cache: dict[Path, os.stat_result] = {}
+    strategy = get_strategy(mode)
+    searcher = VexorSearcher(
+        model_name=model_name,
+        batch_size=batch_size,
+        embed_concurrency=embed_concurrency,
+        provider=provider,
+        base_url=base_url,
+        api_key=api_key,
+        local_cuda=local_cuda,
+    )
+    payloads = strategy.payloads_for_files(files)
+    if not payloads:
+        empty = np.empty((0, 0), dtype=np.float32)
+        metadata = {
+            "index_id": None,
+            "version": CACHE_VERSION,
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+            "root": str(directory),
+            "model": model_name,
+            "include_hidden": include_hidden,
+            "respect_gitignore": respect_gitignore,
+            "recursive": recursive,
+            "mode": mode,
+            "dimension": 0,
+            "exclude_patterns": tuple(exclude_patterns or ()),
+            "extensions": tuple(extensions or ()),
+            "files": [],
+            "chunks": [],
+        }
+        return [], empty, metadata
+
+    labels = [payload.label for payload in payloads]
+    if no_cache:
+        embeddings = searcher.embed_texts(labels)
+        vectors = np.asarray(embeddings, dtype=np.float32)
+    else:
+        vectors = _embed_labels_with_cache(
+            searcher=searcher,
+            model_name=model_name,
+            labels=labels,
+        )
+    entries = _build_index_entries(
+        payloads,
+        vectors,
+        directory,
+        stat_cache=stat_cache,
+    )
+    paths = [entry.path for entry in entries]
+    file_snapshot: dict[str, dict] = {}
+    chunk_entries: list[dict] = []
+    for entry in entries:
+        rel_path = entry.rel_path
+        chunk_entries.append(
+            {
+                "path": rel_path,
+                "absolute": str(entry.path),
+                "mtime": entry.mtime,
+                "size": entry.size_bytes,
+                "preview": entry.preview,
+                "label_hash": entry.label_hash,
+                "chunk_index": entry.chunk_index,
+                "start_line": entry.start_line,
+                "end_line": entry.end_line,
+            }
+        )
+        if rel_path not in file_snapshot:
+            file_snapshot[rel_path] = {
+                "path": rel_path,
+                "absolute": str(entry.path),
+                "mtime": entry.mtime,
+                "size": entry.size_bytes,
+            }
+
+    metadata = {
+        "index_id": None,
+        "version": CACHE_VERSION,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "root": str(directory),
+        "model": model_name,
+        "include_hidden": include_hidden,
+        "respect_gitignore": respect_gitignore,
+        "recursive": recursive,
+        "mode": mode,
+        "dimension": int(vectors.shape[1]) if vectors.size else 0,
+        "exclude_patterns": tuple(exclude_patterns or ()),
+        "extensions": tuple(extensions or ()),
+        "files": list(file_snapshot.values()),
+        "chunks": chunk_entries,
+    }
+    return paths, vectors, metadata
+
+
 def clear_index_entries(
     directory: Path,
     *,
@@ -367,6 +515,7 @@ def _apply_incremental_update(
     exclude_patterns: Sequence[str] | None,
     extensions: Sequence[str] | None,
     stat_cache: MutableMapping[Path, os.stat_result] | None = None,
+    no_cache: bool = False,
 ) -> Path:
     payloads_to_embed, payloads_to_touch = _split_payloads_by_label(
         changed_payloads,
@@ -387,6 +536,7 @@ def _apply_incremental_update(
             searcher=searcher,
             model_name=model_name,
             labels=labels,
+            no_cache=no_cache,
         )
         changed_entries = _build_index_entries(
             payloads_to_embed,
@@ -424,9 +574,13 @@ def _embed_labels_with_cache(
     searcher,
     model_name: str,
     labels: Sequence[str],
+    no_cache: bool = False,
 ) -> np.ndarray:
     if not labels:
         return np.empty((0, 0), dtype=np.float32)
+    if no_cache:
+        vectors = searcher.embed_texts(labels)
+        return np.asarray(vectors, dtype=np.float32)
     from ..cache import embedding_cache_key, load_embedding_cache, store_embedding_cache
 
     hashes = [embedding_cache_key(label) for label in labels]

vexor/services/search_service.py

@@ -45,6 +45,8 @@ class SearchRequest:
     exclude_patterns: tuple[str, ...]
     extensions: tuple[str, ...]
     auto_index: bool = True
+    temporary_index: bool = False
+    no_cache: bool = False
     embed_concurrency: int = DEFAULT_EMBED_CONCURRENCY
     rerank: str = DEFAULT_RERANK
     flashrank_model: str | None = None
@@ -105,6 +107,11 @@ def _normalize_by_max(scores: Sequence[float]) -> list[float]:
     return [score / max_score for score in scores]
 
 
+def _resolve_rerank_candidates(top_k: int) -> int:
+    candidate = int(top_k * 2)
+    return max(20, min(candidate, 150))
+
+
 def _bm25_scores(
     query_tokens: Sequence[str],
     documents: Sequence[Sequence[str]],
@@ -336,6 +343,9 @@ def _apply_remote_rerank(
 def perform_search(request: SearchRequest) -> SearchResponse:
     """Execute the semantic search flow and return ranked results."""
 
+    if request.temporary_index or request.no_cache:
+        return _perform_search_with_temporary_index(request)
+
     from ..cache import (  # local import
         embedding_cache_key,
         list_cache_entries,
@@ -381,6 +391,7 @@ def perform_search(request: SearchRequest) -> SearchResponse:
             local_cuda=request.local_cuda,
             exclude_patterns=request.exclude_patterns,
             extensions=request.extensions,
+            no_cache=request.no_cache,
         )
         if result.status == IndexStatus.EMPTY:
             return SearchResponse(
@@ -461,6 +472,7 @@ def perform_search(request: SearchRequest) -> SearchResponse:
             local_cuda=request.local_cuda,
             exclude_patterns=index_excludes,
             extensions=index_extensions,
+            no_cache=request.no_cache,
         )
         if result.status == IndexStatus.EMPTY:
             return SearchResponse(
@@ -542,9 +554,9 @@ def perform_search(request: SearchRequest) -> SearchResponse:
     )
     query_vector = None
     query_hash = None
-    query_text_hash = embedding_cache_key(request.query)
+    query_text_hash = None
     index_id = metadata.get("index_id")
-    if index_id is not None:
+    if index_id is not None and not request.no_cache:
         query_hash = query_cache_key(request.query, request.model_name)
         try:
             query_vector = load_query_vector(int(index_id), query_hash)
@@ -554,7 +566,8 @@ def perform_search(request: SearchRequest) -> SearchResponse:
         if query_vector is not None and query_vector.size != file_vectors.shape[1]:
             query_vector = None
 
-    if query_vector is None:
+    if query_vector is None and not request.no_cache:
+        query_text_hash = embedding_cache_key(request.query)
         cached = load_embedding_cache(request.model_name, [query_text_hash])
         query_vector = cached.get(query_text_hash)
         if query_vector is not None and query_vector.size != file_vectors.shape[1]:
@@ -562,14 +575,22 @@ def perform_search(request: SearchRequest) -> SearchResponse:
 
     if query_vector is None:
         query_vector = searcher.embed_texts([request.query])[0]
-        try:
-            store_embedding_cache(
-                model=request.model_name,
-                embeddings={query_text_hash: query_vector},
-            )
-        except Exception:  # pragma: no cover - best-effort cache storage
-            pass
-    if query_vector is not None and index_id is not None and query_hash is not None:
+        if not request.no_cache:
+            if query_text_hash is None:
+                query_text_hash = embedding_cache_key(request.query)
+            try:
+                store_embedding_cache(
+                    model=request.model_name,
+                    embeddings={query_text_hash: query_vector},
+                )
+            except Exception:  # pragma: no cover - best-effort cache storage
+                pass
+    if (
+        not request.no_cache
+        and query_vector is not None
+        and index_id is not None
+        and query_hash is not None
+    ):
         try:
             store_query_vector(int(index_id), query_hash, request.query, query_vector)
         except Exception:  # pragma: no cover - best-effort cache storage
@@ -597,7 +618,7 @@ def perform_search(request: SearchRequest) -> SearchResponse:
     reranker = None
     rerank = (request.rerank or DEFAULT_RERANK).strip().lower()
     if rerank in {"bm25", "flashrank", "remote"}:
-        candidate_count = min(len(scored), request.top_k * 2)
+        candidate_count = min(len(scored), _resolve_rerank_candidates(request.top_k))
         candidates = scored[:candidate_count]
         if rerank == "bm25":
             candidates = _apply_bm25_rerank(request.query, candidates)
@@ -629,6 +650,129 @@ def perform_search(request: SearchRequest) -> SearchResponse:
     )
 
 
+def _perform_search_with_temporary_index(request: SearchRequest) -> SearchResponse:
+    from .index_service import build_index_in_memory  # local import
+
+    paths, file_vectors, metadata = build_index_in_memory(
+        request.directory,
+        include_hidden=request.include_hidden,
+        respect_gitignore=request.respect_gitignore,
+        mode=request.mode,
+        recursive=request.recursive,
+        model_name=request.model_name,
+        batch_size=request.batch_size,
+        embed_concurrency=request.embed_concurrency,
+        provider=request.provider,
+        base_url=request.base_url,
+        api_key=request.api_key,
+        local_cuda=request.local_cuda,
+        exclude_patterns=request.exclude_patterns,
+        extensions=request.extensions,
+        no_cache=request.no_cache,
+    )
+
+    if not len(paths):
+        return SearchResponse(
+            base_path=request.directory,
+            backend=None,
+            results=[],
+            is_stale=False,
+            index_empty=True,
+        )
+
+    from sklearn.metrics.pairwise import cosine_similarity  # local import
+    from ..search import SearchResult, VexorSearcher  # local import
+
+    searcher = VexorSearcher(
+        model_name=request.model_name,
+        batch_size=request.batch_size,
+        embed_concurrency=request.embed_concurrency,
+        provider=request.provider,
+        base_url=request.base_url,
+        api_key=request.api_key,
+        local_cuda=request.local_cuda,
+    )
+    query_vector = None
+    query_text_hash = None
+    if not request.no_cache:
+        from ..cache import embedding_cache_key, load_embedding_cache, store_embedding_cache
+
+        query_text_hash = embedding_cache_key(request.query)
+        cached = load_embedding_cache(request.model_name, [query_text_hash])
+        query_vector = cached.get(query_text_hash)
+        if query_vector is not None and query_vector.size != file_vectors.shape[1]:
+            query_vector = None
+
+    if query_vector is None:
+        query_vector = searcher.embed_texts([request.query])[0]
+        if not request.no_cache:
+            if query_text_hash is None:
+                from ..cache import embedding_cache_key, store_embedding_cache
+
+                query_text_hash = embedding_cache_key(request.query)
+            try:
+                store_embedding_cache(
+                    model=request.model_name,
+                    embeddings={query_text_hash: query_vector},
+                )
+            except Exception:  # pragma: no cover - best-effort cache storage
+                pass
+    similarities = cosine_similarity(
+        query_vector.reshape(1, -1),
+        file_vectors,
+    )[0]
+    chunk_entries = metadata.get("chunks", [])
+    scored = []
+    for idx, (path, score) in enumerate(zip(paths, similarities)):
+        chunk_meta = chunk_entries[idx] if idx < len(chunk_entries) else {}
+        start_line = chunk_meta.get("start_line")
+        end_line = chunk_meta.get("end_line")
+        scored.append(
+            SearchResult(
+                path=path,
+                score=float(score),
+                preview=chunk_meta.get("preview"),
+                chunk_index=int(chunk_meta.get("chunk_index", 0)),
+                start_line=int(start_line) if start_line is not None else None,
+                end_line=int(end_line) if end_line is not None else None,
+            )
+        )
+    scored.sort(key=lambda item: item.score, reverse=True)
+    reranker = None
+    rerank = (request.rerank or DEFAULT_RERANK).strip().lower()
+    if rerank in {"bm25", "flashrank", "remote"}:
+        candidate_count = min(len(scored), _resolve_rerank_candidates(request.top_k))
+        candidates = scored[:candidate_count]
+        if rerank == "bm25":
+            candidates = _apply_bm25_rerank(request.query, candidates)
+            reranker = "bm25"
+        elif rerank == "flashrank":
+            candidates = _apply_flashrank_rerank(
+                request.query,
+                candidates,
+                request.flashrank_model,
+            )
+            reranker = "flashrank"
+        else:
+            candidates = _apply_remote_rerank(
+                request.query,
+                candidates,
+                request.remote_rerank,
+            )
+            reranker = "remote"
+        results = candidates[: request.top_k]
+    else:
+        results = scored[: request.top_k]
+    return SearchResponse(
+        base_path=request.directory,
+        backend=searcher.device,
+        results=results,
+        is_stale=False,
+        index_empty=False,
+        reranker=reranker,
+    )
+
+
 def _load_index_vectors_for_request(
     request: SearchRequest,
     *,

vexor/text.py

@@ -19,6 +19,7 @@ class Messages:
     HELP_SEARCH_FORMAT = (
         "Output format (rich=table, porcelain=tab-separated for scripts, porcelain-z=NUL-delimited)."
     )
+    HELP_NO_CACHE = "Disable all disk caches (index + embedding/query)."
     HELP_INCLUDE_HIDDEN = "Use the index built with hidden files included."
     HELP_INDEX_PATH = "Root directory to scan for indexing."
     HELP_INDEX_INCLUDE = "Include hidden files and directories when building the index."
@@ -299,6 +300,8 @@ class Messages:
     ERROR_CONFIG_EDITOR_NOT_FOUND = "Unable to determine a text editor. Set $VISUAL or $EDITOR, or install nano/vi."
     ERROR_CONFIG_EDITOR_FAILED = "Editor exited with status {code}."
     ERROR_CONFIG_EDITOR_LAUNCH = "Failed to launch editor: {reason}."
+    ERROR_CONFIG_JSON_INVALID = "Config JSON must be an object."
+    ERROR_CONFIG_VALUE_INVALID = "Config JSON has invalid value for {field}."
     INFO_CONFIG_SUMMARY = (
         "API key set: {api}\n"
         "Default provider: {provider}\n"
@@ -315,6 +318,7 @@ class Messages:
     INFO_FLASHRANK_MODEL_SUMMARY = "FlashRank model: {value}"
     INFO_REMOTE_RERANK_SUMMARY = "Remote rerank: {value}"
     INFO_SEARCH_RUNNING = "Searching cached index under {path}..."
+    INFO_SEARCH_RUNNING_NO_CACHE = "Searching in-memory index under {path}..."
     INFO_DOCTOR_CHECKING = "Checking if `vexor` is on PATH..."
     INFO_DOCTOR_FOUND = "`vexor` command is available at {path}."
     ERROR_DOCTOR_MISSING = (

{vexor-0.19.0.dist-info → vexor-0.20.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vexor
-Version: 0.19.0
+Version: 0.20.0
 Summary: A vector-powered CLI for semantic search over files.
 Project-URL: Repository, https://github.com/scarletkc/vexor
 Author: scarletkc
@@ -69,9 +69,8 @@ Description-Content-Type: text/markdown
 
 ---
 
-**Vexor** is a vector-powered CLI and desktop app for semantic file search. It uses configurable embedding models and ranks results by cosine similarity.
-
-![GUI](https://raw.githubusercontent.com/scarletkc/vexor/refs/heads/main/assets/gui_demo.png)
+**Vexor** is a semantic search engine that builds reusable indexes over files and code.
+It supports configurable embedding and reranking providers, and exposes the same core through a Python API, a CLI tool, and an optional desktop frontend.
 
 <video src="https://github.com/user-attachments/assets/4d53eefd-ab35-4232-98a7-f8dc005983a9" controls="controls" style="max-width: 600px;">
       Vexor Demo Video
@@ -98,18 +97,13 @@ vexor init
 ```
 The wizard also runs automatically on first use when no config exists.
 
-### 1. Configure API Key
+### 1. Search
 ```bash
-vexor config --set-api-key "YOUR_KEY"
-```
-Or via environment: `VEXOR_API_KEY`, `OPENAI_API_KEY`, or `GOOGLE_GENAI_API_KEY`.
-
-### 2. Search
-```bash
-vexor "api client config"  # defaults to search
-vexor search "api client config"  # searches current directory
+vexor "api client config"  # defaults to search current directory
 # or explicit path:
 vexor search "api client config" --path ~/projects/demo --top 5
+# in-memory search only:
+vexor search "api client config" --no-cache 
 ```
 
 Vexor auto-indexes on first search. Example output:
@@ -122,7 +116,7 @@ Vexor semantic file search results
 3   0.809        ./tests/test_config_loader.py   -       tests for config loader
 ```
 
-### 3. Explicit Index (Optional)
+### 2. Explicit Index (Optional)
 ```bash
 vexor index  # indexes current directory
 # or explicit path:
@@ -130,6 +124,15 @@ vexor index --path ~/projects/demo --mode code
 ```
 Useful for CI warmup or when `auto_index` is disabled.
 
+## Desktop App (Experimental)
+
+> The desktop app is experimental and not actively maintained.
+> It may be unstable. For production use, prefer the CLI.
+
+![GUI](https://raw.githubusercontent.com/scarletkc/vexor/refs/heads/main/assets/gui_demo.png)
+
+Download the desktop app from [releases](https://github.com/scarletkc/vexor/releases).
+
 ## Python API
 
 Vexor can also be imported and used directly from Python:
@@ -144,8 +147,8 @@ for hit in response.results:
     print(hit.path, hit.score)
 ```
 
-By default it reads `~/.vexor/config.json`. To ignore config and pass everything explicitly,
-set `use_config=False`.
+By default it reads `~/.vexor/config.json`. For runtime config overrides, cache
+controls, and per-call options, see [`docs/api/python.md`](https://github.com/scarletkc/vexor/tree/main/docs/api/python.md).
 
 ## Configuration
 
@@ -175,10 +178,16 @@ FlashRank requires `pip install "vexor[flashrank]"` and caches models under `~/.
 
 Config stored in `~/.vexor/config.json`.
 
+### Configure API Key
+```bash
+vexor config --set-api-key "YOUR_KEY"
+```
+Or via environment: `VEXOR_API_KEY`, `OPENAI_API_KEY`, or `GOOGLE_GENAI_API_KEY`.
+
 ### Rerank
 
-Rerank reorders the semantic results with a secondary ranker. It uses 2x the requested
-`--top` as candidates (e.g., top 10 reranked to show 5).
+Rerank reorders the semantic results with a secondary ranker. Candidate sizing uses
+`clamp(int(--top * 2), 20, 150)`.
 
 Recommended defaults:
 - Keep `off` unless you want extra precision.
@@ -285,6 +294,7 @@ Re-running `vexor index` only re-embeds changed files; >50% changes trigger full
 | `--no-respect-gitignore` | Include gitignored files |
 | `--format porcelain` | Script-friendly TSV output |
 | `--format porcelain-z` | NUL-delimited output |
+| `--no-cache` | In-memory only; do not read/write index cache |
 
 Porcelain output fields: `rank`, `similarity`, `path`, `chunk_index`, `start_line`, `end_line`, `preview` (line fields are `-` when unavailable).
 

{vexor-0.19.0.dist-info → vexor-0.20.0.dist-info}/RECORD

@@ -1,13 +1,13 @@
-vexor/__init__.py,sha256=U8AydgyRdjDJj_O_jXldsp43pRctpv57rVOnabjlqEs,367
+vexor/__init__.py,sha256=DAhiDVmFBHG2bu_3wkHBS2OubxR3yjbqa1nFLjQ0-Uw,441
 vexor/__main__.py,sha256=ZFzom1wCfP6TPXe3aoDFpNcUgjbCZ7Quy_vfzNsH5Fw,426
-vexor/api.py,sha256=0O2xYXCYwFjN78Hzrl3c7kpLWkoUoFdX_qlnX8RvqfY,8609
-vexor/cache.py,sha256=VVyPIoijH0m5U98sCpFF5q5pizOx21FGBGmP3HPN7eI,44720
-vexor/cli.py,sha256=EKNbSrYQQpD_zzaYRw8tApHlXzA2gLbx8wLSAd_dWaQ,65199
-vexor/config.py,sha256=dFiZrOTAxcvxDNKM6cnVGK98M1q9LzxdqmiceUmngow,8827
+vexor/api.py,sha256=84GxMt4laq9bpfesPJSFUzkTTCrCpIDDRpVLXKGZ-rg,10470
+vexor/cache.py,sha256=B1seuKU0eYLNvFi7Lpy_X13cSvBfhsuQeH4rZ7Hc29Y,45106
+vexor/cli.py,sha256=hnANtRGO5ypEftMyuTmlZhttSuBZy9ivxymQK11gZ9c,65736
+vexor/config.py,sha256=f5Wom1yUzScp52xpdhLlCG6x7ZEgtFV7kQlarxvD9hU,15372
 vexor/modes.py,sha256=N_wAWoqbxmCfko-v520p59tpAYvUwraCSSQRtMaF4ac,11549
 vexor/output.py,sha256=iooZgLlK8dh7ajJ4XMHUNNx0qyTVtD_OAAwrBx5MeqE,864
 vexor/search.py,sha256=MSU4RmH6waFYOofkIdo8_ElTiz1oNaKuvr-3umif7Bs,6826
-vexor/text.py,sha256=ZgnGF0_92eU_3AtTRrv5NbE_AhDggMmhCQSvTGRlQ3Q,23876
+vexor/text.py,sha256=ntqwx2hP5QtlUXnIvBh1NFSn8cxRVhvYtFb7aMt_Tus,24171
 vexor/utils.py,sha256=GzfYW2rz1-EuJjkevqZVe8flLRtrQ60OWMmFNbMh62k,12472
 vexor/providers/__init__.py,sha256=kCEoV03TSLKcxDUYVNjXnrVoLU5NpfNXjp1w1Ak2imE,92
 vexor/providers/gemini.py,sha256=-bKSubZRELefJmZzclepXNSWUPsXo94EAM9l0JtfbFM,3739
@@ -17,17 +17,17 @@ vexor/services/__init__.py,sha256=dA_i2N03vlYmbZbEK2knzJLWviunkNWbzN2LWPNvMk0,16
 vexor/services/cache_service.py,sha256=ywt6AgupCJ7_wC3je4znCMw5_VBouw3skbDTAt8xw6o,1639
 vexor/services/config_service.py,sha256=yJTBbOmxpbzskHPuLlxYXQ-COJC6-qKtvMsSfuneJoA,4471
 vexor/services/content_extract_service.py,sha256=zdhLxpNv70BU7irLf3Uc0ou9rKSvdjtrDcHkgRKlMn4,26421
-vexor/services/index_service.py,sha256=krF2BSOV6ucLK1tCB1Kp2GR7Qae15bFbRC4abYq7Qxw,23273
+vexor/services/index_service.py,sha256=pteAG-eRA8FJmDc4GEwhHXGZE8Dm5L8uqzBB0Y8Rrgo,28312
 vexor/services/init_service.py,sha256=3D04hylGA9FRQhLHCfR95nMko3vb5MNBcRb9nWWaUE8,26863
 vexor/services/js_parser.py,sha256=eRtW6KlK4JBYDGbyoecHVqLZ0hcx-Cc0kx6bOujHPAQ,16254
 vexor/services/keyword_service.py,sha256=vmke8tII9kTwRDdBaLHBc6Hpy_B3p98L65iGkCQgtMU,2211
-vexor/services/search_service.py,sha256=q7ppAkvtNRvFY0NyJZVJfQyXbVkiSMY1ezRvI8Ox33c,30787
+vexor/services/search_service.py,sha256=_3WMzHNV0MCGWFXqwYCQ-XF08aJwF9L4mOGGnmXOATs,36076
 vexor/services/skill_service.py,sha256=Rrgt3OMsKPPiXOiRhSNAWjBM9UNz9qmSWQe3uYGzq4M,4863
 vexor/services/system_service.py,sha256=KPlv83v3rTvBiNiH7vrp6tDmt_AqHxuUd-5RI0TfvWs,24638
-vexor/_bundled_skills/vexor-cli/SKILL.md,sha256=QHiBBO0McV_5HxYqm0ANVA_r4-OPOxRhcxWT2O9QMJQ,2736
+vexor/_bundled_skills/vexor-cli/SKILL.md,sha256=m3FlyqgHBdRwyGPEp8PrUS21K0G2jEl88tRvhSPta08,2798
 vexor/_bundled_skills/vexor-cli/references/install-vexor.md,sha256=IUBShLI1mAxugwUIMAJQ5_j6KcaPWfobe0gSd6MWU7w,1245
-vexor-0.19.0.dist-info/METADATA,sha256=L8Y_RhPH6QfYmjM54STyuaCECC3_JKSaI-EV_rdwJDM,12853
-vexor-0.19.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-vexor-0.19.0.dist-info/entry_points.txt,sha256=dvxp6Q1R1d6bozR7TwmpdJ0X_v83MkzsLPagGY_lfr0,40
-vexor-0.19.0.dist-info/licenses/LICENSE,sha256=wP7TAKRll1t9LoYGxWS9NikPM_0hCc00LmlLyvQBsL8,1066
-vexor-0.19.0.dist-info/RECORD,,
+vexor-0.20.0.dist-info/METADATA,sha256=RBTym4NL38S6OjijOg5fWPW9VmD7AuLEEqjZtQMkZqA,13331
+vexor-0.20.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+vexor-0.20.0.dist-info/entry_points.txt,sha256=dvxp6Q1R1d6bozR7TwmpdJ0X_v83MkzsLPagGY_lfr0,40
+vexor-0.20.0.dist-info/licenses/LICENSE,sha256=wP7TAKRll1t9LoYGxWS9NikPM_0hCc00LmlLyvQBsL8,1066
+vexor-0.20.0.dist-info/RECORD,,