vexor 0.19.0a1__tar.gz → 0.21.0__tar.gz

{vexor-0.19.0a1 → vexor-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vexor
-Version: 0.19.0a1
+Version: 0.21.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
-```bash
-vexor config --set-api-key "YOUR_KEY"
-```
-Or via environment: `VEXOR_API_KEY`, `OPENAI_API_KEY`, or `GOOGLE_GENAI_API_KEY`.
-
-### 2. Search
+### 1. 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,19 @@ 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).
+
+## AI Agent Skill
+
+This repo includes a skill for AI agents to use Vexor effectively:
+
+```bash
+vexor install --skills claude  # Claude Code
+vexor install --skills codex   # Codex
+```
+
+Skill source: [`plugins/vexor/skills/vexor-cli`](https://github.com/scarletkc/vexor/raw/refs/heads/main/plugins/vexor/skills/vexor-cli/SKILL.md)
 
 ## Configuration
 
@@ -153,7 +167,9 @@ set `use_config=False`.
 vexor config --set-provider openai          # default; also supports gemini/custom/local
 vexor config --set-model text-embedding-3-small
 vexor config --set-batch-size 0             # 0 = single request
-vexor config --set-embed-concurrency 2       # parallel embedding requests
+vexor config --set-embed-concurrency 4       # parallel embedding requests
+vexor config --set-extract-concurrency 4     # parallel file extraction workers
+vexor config --set-extract-backend auto      # auto|thread|process (default: auto)
 vexor config --set-auto-index true          # auto-index before search (default)
 vexor config --rerank bm25                  # optional BM25 rerank for top-k results
 vexor config --rerank flashrank             # FlashRank rerank (requires optional extra)
@@ -175,10 +191,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,20 +307,10 @@ 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).
 
-## AI Agent Skill
-
-This repo includes a skill for AI agents to use Vexor effectively:
-
-```bash
-vexor install --skills claude  # Claude Code
-vexor install --skills codex   # Codex
-```
-
-Skill source: [`plugins/vexor/skills/vexor-cli`](https://github.com/scarletkc/vexor/raw/refs/heads/main/plugins/vexor/skills/vexor-cli/SKILL.md)
-
 ## Documentation
 
 See [docs](https://github.com/scarletkc/vexor/tree/main/docs) for more details.

{vexor-0.19.0a1 → vexor-0.21.0}/README.md

@@ -14,9 +14,8 @@
 
 ---
 
-**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
@@ -43,18 +42,13 @@ vexor init
 ```
 The wizard also runs automatically on first use when no config exists.
 
-### 1. 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`.
-
-### 2. Search
+### 1. 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:
@@ -67,7 +61,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:
@@ -75,6 +69,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:
@@ -89,8 +92,19 @@ 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).
+
+## AI Agent Skill
+
+This repo includes a skill for AI agents to use Vexor effectively:
+
+```bash
+vexor install --skills claude  # Claude Code
+vexor install --skills codex   # Codex
+```
+
+Skill source: [`plugins/vexor/skills/vexor-cli`](https://github.com/scarletkc/vexor/raw/refs/heads/main/plugins/vexor/skills/vexor-cli/SKILL.md)
 
 ## Configuration
 
@@ -98,7 +112,9 @@ set `use_config=False`.
 vexor config --set-provider openai          # default; also supports gemini/custom/local
 vexor config --set-model text-embedding-3-small
 vexor config --set-batch-size 0             # 0 = single request
-vexor config --set-embed-concurrency 2       # parallel embedding requests
+vexor config --set-embed-concurrency 4       # parallel embedding requests
+vexor config --set-extract-concurrency 4     # parallel file extraction workers
+vexor config --set-extract-backend auto      # auto|thread|process (default: auto)
 vexor config --set-auto-index true          # auto-index before search (default)
 vexor config --rerank bm25                  # optional BM25 rerank for top-k results
 vexor config --rerank flashrank             # FlashRank rerank (requires optional extra)
@@ -120,10 +136,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.
@@ -230,20 +252,10 @@ 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).
 
-## AI Agent Skill
-
-This repo includes a skill for AI agents to use Vexor effectively:
-
-```bash
-vexor install --skills claude  # Claude Code
-vexor install --skills codex   # Codex
-```
-
-Skill source: [`plugins/vexor/skills/vexor-cli`](https://github.com/scarletkc/vexor/raw/refs/heads/main/plugins/vexor/skills/vexor-cli/SKILL.md)
-
 ## Documentation
 
 See [docs](https://github.com/scarletkc/vexor/tree/main/docs) for more details.

{vexor-0.19.0a1 → vexor-0.21.0}/plugins/vexor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vexor",
-  "version": "0.19.0a1",
+  "version": "0.21.0",
   "description": "A vector-powered CLI for semantic search over files (Vexor skill bundle).",
   "author": {
     "name": "scarletkc"

{vexor-0.19.0a1 → vexor-0.21.0}/plugins/vexor/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-0.19.0a1 → vexor-0.21.0}/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.0a1"
+__version__ = "0.21.0"
 
 
 def get_version() -> str:

{vexor-0.19.0a1 → vexor-0.21.0}/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
@@ -38,6 +42,8 @@ class RuntimeSettings:
     model_name: str
     batch_size: int
     embed_concurrency: int
+    extract_concurrency: int
+    extract_backend: str
     base_url: str | None
     api_key: str | None
     local_cuda: bool
@@ -47,6 +53,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,
     *,
@@ -62,11 +92,16 @@ def search(
     model: str | None = None,
     batch_size: int | None = None,
     embed_concurrency: int | None = None,
+    extract_concurrency: int | None = None,
+    extract_backend: str | None = None,
     base_url: str | None = None,
     api_key: str | None = None,
     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."""
 
@@ -90,11 +125,15 @@ def search(
         model=model,
         batch_size=batch_size,
         embed_concurrency=embed_concurrency,
+        extract_concurrency=extract_concurrency,
+        extract_backend=extract_backend,
         base_url=base_url,
         api_key=api_key,
         local_cuda=local_cuda,
         auto_index=auto_index,
         use_config=use_config,
+        runtime_config=_RUNTIME_CONFIG,
+        config_override=config,
     )
 
     request = SearchRequest(
@@ -108,6 +147,8 @@ def search(
         model_name=settings.model_name,
         batch_size=settings.batch_size,
         embed_concurrency=settings.embed_concurrency,
+        extract_concurrency=settings.extract_concurrency,
+        extract_backend=settings.extract_backend,
         provider=settings.provider,
         base_url=settings.base_url,
         api_key=settings.api_key,
@@ -115,6 +156,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,
@@ -135,10 +178,13 @@ def index(
     model: str | None = None,
     batch_size: int | None = None,
     embed_concurrency: int | None = None,
+    extract_concurrency: int | None = None,
+    extract_backend: str | None = None,
     base_url: str | None = None,
     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."""
 
@@ -154,11 +200,15 @@ def index(
         model=model,
         batch_size=batch_size,
         embed_concurrency=embed_concurrency,
+        extract_concurrency=extract_concurrency,
+        extract_backend=extract_backend,
         base_url=base_url,
         api_key=api_key,
         local_cuda=local_cuda,
         auto_index=None,
         use_config=use_config,
+        runtime_config=_RUNTIME_CONFIG,
+        config_override=config,
     )
 
     return build_index(
@@ -170,6 +220,8 @@ def index(
         model_name=settings.model_name,
         batch_size=settings.batch_size,
         embed_concurrency=settings.embed_concurrency,
+        extract_concurrency=settings.extract_concurrency,
+        extract_backend=settings.extract_backend,
         provider=settings.provider,
         base_url=settings.base_url,
         api_key=settings.api_key,
@@ -220,6 +272,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))
 
@@ -242,13 +296,23 @@ def _resolve_settings(
     model: str | None,
     batch_size: int | None,
     embed_concurrency: int | None,
+    extract_concurrency: int | None,
+    extract_backend: str | None,
     base_url: str | None,
     api_key: str | None,
     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:
@@ -265,11 +329,21 @@ def _resolve_settings(
     embed_value = (
         embed_concurrency if embed_concurrency is not None else config.embed_concurrency
     )
+    extract_value = (
+        extract_concurrency
+        if extract_concurrency is not None
+        else config.extract_concurrency
+    )
+    extract_backend_value = (
+        extract_backend if extract_backend is not None else config.extract_backend
+    )
     return RuntimeSettings(
         provider=provider_value,
         model_name=model_name,
         batch_size=batch_value,
         embed_concurrency=embed_value,
+        extract_concurrency=extract_value,
+        extract_backend=extract_backend_value,
         base_url=base_url if base_url is not None else config.base_url,
         api_key=api_key if api_key is not None else config.api_key,
         local_cuda=bool(local_cuda if local_cuda is not None else config.local_cuda),
@@ -278,3 +352,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