vexor 0.22.0__tar.gz → 0.23.0rc1__tar.gz

{vexor-0.22.0 → vexor-0.23.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vexor
-Version: 0.22.0
+Version: 0.23.0rc1
 Summary: A vector-powered CLI for semantic search over files.
 Project-URL: Repository, https://github.com/scarletkc/vexor
 Author: scarletkc
@@ -22,7 +22,7 @@ Classifier: Topic :: Text Processing :: Indexing
 Classifier: Topic :: Utilities
 Requires-Python: >=3.9
 Requires-Dist: charset-normalizer>=3.3.0
-Requires-Dist: google-genai>=0.5.0
+Requires-Dist: google-genai>=1.57.0
 Requires-Dist: numpy>=1.23.0
 Requires-Dist: openai>=1.0.0
 Requires-Dist: pathspec>=0.12.1
@@ -64,6 +64,7 @@ Description-Content-Type: text/markdown
 [![CI](https://img.shields.io/github/actions/workflow/status/scarletkc/vexor/publish.yml?branch=main)](https://github.com/scarletkc/vexor/actions/workflows/publish.yml)
 [![Codecov](https://img.shields.io/codecov/c/github/scarletkc/vexor/main)](https://codecov.io/github/scarletkc/vexor)
 [![License](https://img.shields.io/github/license/scarletkc/vexor.svg)](https://github.com/scarletkc/vexor/blob/main/LICENSE)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/scarletkc/vexor)
 
 </div>
 
@@ -171,12 +172,15 @@ Skill source: [`plugins/vexor/skills/vexor-cli`](https://github.com/scarletkc/ve
 ## Configuration
 
 ```bash
-vexor config --set-provider openai          # default; also supports gemini/custom/local
+vexor config --set-provider openai          # default; also supports gemini/voyageai/custom/local
 vexor config --set-model text-embedding-3-small
+vexor config --set-provider voyageai        # uses voyage defaults when model/base_url are unset
 vexor config --set-batch-size 0             # 0 = single request
 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-embedding-dimensions 1024 # optional, model/provider dependent
+vexor config --clear-embedding-dimensions    # reset to model default dimension
 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)
@@ -202,7 +206,7 @@ Config stored in `~/.vexor/config.json`.
 ```bash
 vexor config --set-api-key "YOUR_KEY"
 ```
-Or via environment: `VEXOR_API_KEY`, `OPENAI_API_KEY`, or `GOOGLE_GENAI_API_KEY`.
+Or via environment: `VEXOR_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENAI_API_KEY`, or `VOYAGE_API_KEY`.
 
 ### Rerank
 
@@ -222,11 +226,30 @@ Recommended defaults:
 
 ### Providers: Remote vs Local
 
-Vexor supports both remote API providers (`openai`, `gemini`, `custom`) and a local provider (`local`):
+Vexor supports both remote API providers (`openai`, `gemini`, `voyageai`, `custom`) and a local provider (`local`):
 - Remote providers use `api_key` and optional `base_url`.
+- `voyageai` defaults to `https://api.voyageai.com/v1` when `base_url` is not set.
 - `custom` is OpenAI-compatible and requires both `model` and `base_url`.
 - Local provider ignores `api_key/base_url` and only uses `model` plus `local_cuda` (CPU/GPU switch).
 
+### Embedding Dimensions
+
+Embedding dimensions are optional. If unset, the provider/model default is used.
+Custom dimensions are validated for:
+- OpenAI `text-embedding-3-*`
+- Voyage `voyage-3*` and `voyage-code-3*`
+
+```bash
+vexor config --set-embedding-dimensions 1024
+vexor config --clear-embedding-dimensions
+```
+
+If you change dimensions after an index is built, rebuild the index:
+
+```bash
+vexor index --path .
+```
+
 ### Local Model (Offline)
 
 Install the lightweight local backend:

{vexor-0.22.0 → vexor-0.23.0rc1}/README.md

@@ -9,6 +9,7 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/scarletkc/vexor/publish.yml?branch=main)](https://github.com/scarletkc/vexor/actions/workflows/publish.yml)
 [![Codecov](https://img.shields.io/codecov/c/github/scarletkc/vexor/main)](https://codecov.io/github/scarletkc/vexor)
 [![License](https://img.shields.io/github/license/scarletkc/vexor.svg)](https://github.com/scarletkc/vexor/blob/main/LICENSE)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/scarletkc/vexor)
 
 </div>
 
@@ -116,12 +117,15 @@ Skill source: [`plugins/vexor/skills/vexor-cli`](https://github.com/scarletkc/ve
 ## Configuration
 
 ```bash
-vexor config --set-provider openai          # default; also supports gemini/custom/local
+vexor config --set-provider openai          # default; also supports gemini/voyageai/custom/local
 vexor config --set-model text-embedding-3-small
+vexor config --set-provider voyageai        # uses voyage defaults when model/base_url are unset
 vexor config --set-batch-size 0             # 0 = single request
 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-embedding-dimensions 1024 # optional, model/provider dependent
+vexor config --clear-embedding-dimensions    # reset to model default dimension
 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)
@@ -147,7 +151,7 @@ Config stored in `~/.vexor/config.json`.
 ```bash
 vexor config --set-api-key "YOUR_KEY"
 ```
-Or via environment: `VEXOR_API_KEY`, `OPENAI_API_KEY`, or `GOOGLE_GENAI_API_KEY`.
+Or via environment: `VEXOR_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENAI_API_KEY`, or `VOYAGE_API_KEY`.
 
 ### Rerank
 
@@ -167,11 +171,30 @@ Recommended defaults:
 
 ### Providers: Remote vs Local
 
-Vexor supports both remote API providers (`openai`, `gemini`, `custom`) and a local provider (`local`):
+Vexor supports both remote API providers (`openai`, `gemini`, `voyageai`, `custom`) and a local provider (`local`):
 - Remote providers use `api_key` and optional `base_url`.
+- `voyageai` defaults to `https://api.voyageai.com/v1` when `base_url` is not set.
 - `custom` is OpenAI-compatible and requires both `model` and `base_url`.
 - Local provider ignores `api_key/base_url` and only uses `model` plus `local_cuda` (CPU/GPU switch).
 
+### Embedding Dimensions
+
+Embedding dimensions are optional. If unset, the provider/model default is used.
+Custom dimensions are validated for:
+- OpenAI `text-embedding-3-*`
+- Voyage `voyage-3*` and `voyage-code-3*`
+
+```bash
+vexor config --set-embedding-dimensions 1024
+vexor config --clear-embedding-dimensions
+```
+
+If you change dimensions after an index is built, rebuild the index:
+
+```bash
+vexor index --path .
+```
+
 ### Local Model (Offline)
 
 Install the lightweight local backend:

{vexor-0.22.0 → vexor-0.23.0rc1}/plugins/vexor/.claude-plugin/plugin.json

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

{vexor-0.22.0 → vexor-0.23.0rc1}/pyproject.toml

@@ -27,7 +27,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Information Analysis",
 ]
 dependencies = [
-    "google-genai>=0.5.0",
+    "google-genai>=1.57.0",
     "openai>=1.0.0",
     "python-dotenv>=1.0.0",
     "pathspec>=0.12.1",

{vexor-0.22.0 → vexor-0.23.0rc1}/vexor/__init__.py

@@ -30,7 +30,7 @@ __all__ = [
     "set_data_dir",
 ]
 
-__version__ = "0.22.0"
+__version__ = "0.23.0rc1"
 
 
 def get_version() -> str:

{vexor-0.22.0 → vexor-0.23.0rc1}/vexor/api.py

@@ -21,6 +21,7 @@ from .config import (
     SUPPORTED_RERANKERS,
     config_from_json,
     config_dir_context,
+    validate_embedding_dimensions_for_model,
     load_config,
     resolve_default_model,
     set_config_dir,
@@ -67,6 +68,7 @@ class RuntimeSettings:
     rerank: str
     flashrank_model: str | None
     remote_rerank: RemoteRerankConfig | None
+    embedding_dimensions: int | None
 
 
 @dataclass(slots=True)
@@ -82,6 +84,7 @@ class InMemoryIndex:
     base_url: str | None
     api_key: str | None
     local_cuda: bool
+    embedding_dimensions: int | None = None
     rerank: str = DEFAULT_RERANK
     flashrank_model: str | None = None
     remote_rerank: RemoteRerankConfig | None = None
@@ -140,6 +143,7 @@ class InMemoryIndex:
             temporary_index=True,
             no_cache=no_cache,
             rerank=effective_rerank,
+            embedding_dimensions=self.embedding_dimensions,
             flashrank_model=(
                 flashrank_model
                 if flashrank_model is not None
@@ -282,6 +286,7 @@ class VexorClient:
         base_url: str | None = None,
         api_key: str | None = None,
         local_cuda: bool | None = None,
+        embedding_dimensions: int | None = None,
         auto_index: bool | None = None,
         use_config: bool | None = None,
         config: Config | Mapping[str, object] | str | None = None,
@@ -316,6 +321,7 @@ class VexorClient:
             base_url=base_url,
             api_key=api_key,
             local_cuda=local_cuda,
+            embedding_dimensions=embedding_dimensions,
             auto_index=auto_index,
             use_config=resolved_use_config,
             config=config,
@@ -346,6 +352,7 @@ class VexorClient:
         base_url: str | None = None,
         api_key: str | None = None,
         local_cuda: bool | None = None,
+        embedding_dimensions: int | None = None,
         use_config: bool | None = None,
         config: Config | Mapping[str, object] | str | None = None,
         data_dir: Path | str | None = None,
@@ -375,6 +382,7 @@ class VexorClient:
             base_url=base_url,
             api_key=api_key,
             local_cuda=local_cuda,
+            embedding_dimensions=embedding_dimensions,
             use_config=resolved_use_config,
             config=config,
             runtime_config=self._runtime_config,
@@ -402,6 +410,7 @@ class VexorClient:
         base_url: str | None = None,
         api_key: str | None = None,
         local_cuda: bool | None = None,
+        embedding_dimensions: int | None = None,
         use_config: bool | None = None,
         config: Config | Mapping[str, object] | str | None = None,
         no_cache: bool = True,
@@ -432,6 +441,7 @@ class VexorClient:
             base_url=base_url,
             api_key=api_key,
             local_cuda=local_cuda,
+            embedding_dimensions=embedding_dimensions,
             use_config=resolved_use_config,
             config=config,
             no_cache=no_cache,
@@ -518,6 +528,7 @@ def search(
     base_url: str | None = None,
     api_key: str | None = None,
     local_cuda: bool | None = None,
+    embedding_dimensions: int | None = None,
     auto_index: bool | None = None,
     use_config: bool = True,
     config: Config | Mapping[str, object] | str | None = None,
@@ -547,6 +558,7 @@ def search(
         base_url=base_url,
         api_key=api_key,
         local_cuda=local_cuda,
+        embedding_dimensions=embedding_dimensions,
         auto_index=auto_index,
         use_config=use_config,
         config=config,
@@ -577,6 +589,7 @@ def index(
     base_url: str | None = None,
     api_key: str | None = None,
     local_cuda: bool | None = None,
+    embedding_dimensions: int | None = None,
     use_config: bool = True,
     config: Config | Mapping[str, object] | str | None = None,
     data_dir: Path | str | None = None,
@@ -601,6 +614,7 @@ def index(
         base_url=base_url,
         api_key=api_key,
         local_cuda=local_cuda,
+        embedding_dimensions=embedding_dimensions,
         use_config=use_config,
         config=config,
         runtime_config=_RUNTIME_CONFIG,
@@ -628,6 +642,7 @@ def index_in_memory(
     base_url: str | None = None,
     api_key: str | None = None,
     local_cuda: bool | None = None,
+    embedding_dimensions: int | None = None,
     use_config: bool = True,
     config: Config | Mapping[str, object] | str | None = None,
     no_cache: bool = True,
@@ -653,6 +668,7 @@ def index_in_memory(
         base_url=base_url,
         api_key=api_key,
         local_cuda=local_cuda,
+        embedding_dimensions=embedding_dimensions,
         use_config=use_config,
         config=config,
         no_cache=no_cache,
@@ -711,6 +727,7 @@ def _search_with_settings(
     base_url: str | None,
     api_key: str | None,
     local_cuda: bool | None,
+    embedding_dimensions: int | None,
     auto_index: bool | None,
     use_config: bool,
     config: Config | Mapping[str, object] | str | None,
@@ -747,6 +764,7 @@ def _search_with_settings(
             base_url=base_url,
             api_key=api_key,
             local_cuda=local_cuda,
+            embedding_dimensions=embedding_dimensions,
             auto_index=auto_index,
             use_config=use_config,
             runtime_config=runtime_config,
@@ -776,6 +794,7 @@ def _search_with_settings(
             temporary_index=temporary_index,
             no_cache=no_cache,
             rerank=settings.rerank,
+            embedding_dimensions=settings.embedding_dimensions,
             flashrank_model=settings.flashrank_model,
             remote_rerank=settings.remote_rerank,
         )
@@ -800,6 +819,7 @@ def _index_with_settings(
     base_url: str | None,
     api_key: str | None,
     local_cuda: bool | None,
+    embedding_dimensions: int | None,
     use_config: bool,
     config: Config | Mapping[str, object] | str | None,
     runtime_config: Config | None,
@@ -825,6 +845,7 @@ def _index_with_settings(
             base_url=base_url,
             api_key=api_key,
             local_cuda=local_cuda,
+            embedding_dimensions=embedding_dimensions,
             auto_index=None,
             use_config=use_config,
             runtime_config=runtime_config,
@@ -846,6 +867,7 @@ def _index_with_settings(
             base_url=settings.base_url,
             api_key=settings.api_key,
             local_cuda=settings.local_cuda,
+            embedding_dimensions=settings.embedding_dimensions,
             exclude_patterns=normalized_excludes,
             extensions=normalized_exts,
         )
@@ -869,6 +891,7 @@ def _index_in_memory_with_settings(
     base_url: str | None,
     api_key: str | None,
     local_cuda: bool | None,
+    embedding_dimensions: int | None,
     use_config: bool,
     config: Config | Mapping[str, object] | str | None,
     no_cache: bool,
@@ -895,6 +918,7 @@ def _index_in_memory_with_settings(
             base_url=base_url,
             api_key=api_key,
             local_cuda=local_cuda,
+            embedding_dimensions=embedding_dimensions,
             auto_index=None,
             use_config=use_config,
             runtime_config=runtime_config,
@@ -916,6 +940,7 @@ def _index_in_memory_with_settings(
             base_url=settings.base_url,
             api_key=settings.api_key,
             local_cuda=settings.local_cuda,
+            embedding_dimensions=settings.embedding_dimensions,
             exclude_patterns=normalized_excludes,
             extensions=normalized_exts,
             no_cache=no_cache,
@@ -933,6 +958,7 @@ def _index_in_memory_with_settings(
             base_url=settings.base_url,
             api_key=settings.api_key,
             local_cuda=settings.local_cuda,
+            embedding_dimensions=settings.embedding_dimensions,
             rerank=settings.rerank,
             flashrank_model=settings.flashrank_model,
             remote_rerank=settings.remote_rerank,
@@ -1011,6 +1037,7 @@ def _resolve_settings(
     base_url: str | None,
     api_key: str | None,
     local_cuda: bool | None,
+    embedding_dimensions: int | None,
     auto_index: bool | None,
     use_config: bool,
     runtime_config: Config | None = None,
@@ -1047,6 +1074,19 @@ def _resolve_settings(
     extract_backend_value = (
         extract_backend if extract_backend is not None else config.extract_backend
     )
+    resolved_embedding_dimensions = _coerce_embedding_dimensions(
+        embedding_dimensions
+        if embedding_dimensions is not None
+        else config.embedding_dimensions
+    )
+    try:
+        validate_embedding_dimensions_for_model(
+            resolved_embedding_dimensions,
+            model_name,
+        )
+    except ValueError as exc:
+        raise VexorError(str(exc)) from exc
+
     return RuntimeSettings(
         provider=provider_value,
         model_name=model_name,
@@ -1061,6 +1101,7 @@ def _resolve_settings(
         rerank=rerank_value,
         flashrank_model=config.flashrank_model,
         remote_rerank=config.remote_rerank,
+        embedding_dimensions=resolved_embedding_dimensions,
     )
 
 
@@ -1074,3 +1115,17 @@ def _apply_config_override(
         return config_from_json(override, base=base)
     except ValueError as exc:
         raise VexorError(str(exc)) from exc
+
+
+def _coerce_embedding_dimensions(value: int | None) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        raise VexorError(Messages.ERROR_EMBEDDING_DIMENSIONS_INVALID)
+    if not isinstance(value, int):
+        raise VexorError(Messages.ERROR_EMBEDDING_DIMENSIONS_INVALID)
+    if value == 0:
+        return None
+    if value < 0:
+        raise VexorError(Messages.ERROR_EMBEDDING_DIMENSIONS_INVALID)
+    return value

{vexor-0.22.0 → vexor-0.23.0rc1}/vexor/cache.py

@@ -30,7 +30,7 @@ EMBED_CACHE_TTL_DAYS = 30
 EMBED_CACHE_MAX_ENTRIES = 50_000
 EMBED_MEMORY_CACHE_MAX_ENTRIES = 2_048
 
-_EMBED_MEMORY_CACHE: "OrderedDict[tuple[str, str], np.ndarray]" = OrderedDict()
+_EMBED_MEMORY_CACHE: "OrderedDict[tuple[str, int | None, str], np.ndarray]" = OrderedDict()
 _EMBED_MEMORY_LOCK = Lock()
 
 
@@ -89,11 +89,20 @@ def query_cache_key(query: str, model: str) -> str:
     return hashlib.sha1(base.encode("utf-8")).hexdigest()
 
 
-def embedding_cache_key(text: str) -> str:
-    """Return a stable hash for embedding cache lookups."""
+def embedding_cache_key(text: str, dimension: int | None = None) -> str:
+    """Return a stable hash for embedding cache lookups.
 
+    Args:
+        text: The text to hash
+        dimension: Optional embedding dimension (included in hash for dimension-aware caching)
+    """
     clean_text = text or ""
-    return hashlib.sha1(clean_text.encode("utf-8")).hexdigest()
+    # Include dimension in hash to prevent cross-dimension cache pollution
+    if dimension is not None:
+        base = f"{clean_text}|dim={dimension}"
+    else:
+        base = clean_text
+    return hashlib.sha1(base.encode("utf-8")).hexdigest()
 
 
 def _clear_embedding_memory_cache() -> None:
@@ -106,6 +115,7 @@ def _clear_embedding_memory_cache() -> None:
 def _load_embedding_memory_cache(
     model: str,
     text_hashes: Sequence[str],
+    dimension: int | None = None,
 ) -> dict[str, np.ndarray]:
     if EMBED_MEMORY_CACHE_MAX_ENTRIES <= 0:
         return {}
@@ -114,7 +124,8 @@ def _load_embedding_memory_cache(
         for text_hash in text_hashes:
             if not text_hash:
                 continue
-            key = (model, text_hash)
+            # Include dimension in cache key to prevent cross-dimension pollution
+            key = (model, dimension, text_hash)
             vector = _EMBED_MEMORY_CACHE.pop(key, None)
             if vector is None:
                 continue
@@ -127,6 +138,7 @@ def _store_embedding_memory_cache(
     *,
     model: str,
     embeddings: Mapping[str, np.ndarray],
+    dimension: int | None = None,
 ) -> None:
     if EMBED_MEMORY_CACHE_MAX_ENTRIES <= 0 or not embeddings:
         return
@@ -137,7 +149,8 @@ def _store_embedding_memory_cache(
             array = np.asarray(vector, dtype=np.float32)
             if array.size == 0:
                 continue
-            key = (model, text_hash)
+            # Include dimension in cache key to prevent cross-dimension pollution
+            key = (model, dimension, text_hash)
             if key in _EMBED_MEMORY_CACHE:
                 _EMBED_MEMORY_CACHE.pop(key, None)
             _EMBED_MEMORY_CACHE[key] = array
@@ -1388,13 +1401,22 @@ def load_embedding_cache(
     model: str,
     text_hashes: Sequence[str],
     conn: sqlite3.Connection | None = None,
+    *,
+    dimension: int | None = None,
 ) -> dict[str, np.ndarray]:
-    """Load cached embeddings keyed by (model, text_hash)."""
-
+    """Load cached embeddings keyed by (model, text_hash).
+
+    Args:
+        model: The embedding model name
+        text_hashes: Sequence of text hashes to look up (should be generated with
+            embedding_cache_key() using the same dimension parameter)
+        conn: Optional database connection
+        dimension: Embedding dimension (used for memory cache segmentation)
+    """
     unique_hashes = list(dict.fromkeys([value for value in text_hashes if value]))
     if not unique_hashes:
         return {}
-    results = _load_embedding_memory_cache(model, unique_hashes)
+    results = _load_embedding_memory_cache(model, unique_hashes, dimension=dimension)
     missing = [value for value in unique_hashes if value not in results]
     if not missing:
         return results
@@ -1429,7 +1451,9 @@ def load_embedding_cache(
                     continue
                 disk_results[row["text_hash"]] = vector
         if disk_results:
-            _store_embedding_memory_cache(model=model, embeddings=disk_results)
+            _store_embedding_memory_cache(
+                model=model, embeddings=disk_results, dimension=dimension
+            )
             results.update(disk_results)
         return results
     finally:
@@ -1442,12 +1466,20 @@ def store_embedding_cache(
     model: str,
     embeddings: Mapping[str, np.ndarray],
     conn: sqlite3.Connection | None = None,
+    dimension: int | None = None,
 ) -> None:
-    """Store embedding vectors keyed by (model, text_hash)."""
-
+    """Store embedding vectors keyed by (model, text_hash).
+
+    Args:
+        model: The embedding model name
+        embeddings: Dict mapping text_hash -> vector (hashes should be generated with
+            embedding_cache_key() using the same dimension parameter)
+        conn: Optional database connection
+        dimension: Embedding dimension (used for memory cache segmentation)
+    """
     if not embeddings:
         return
-    _store_embedding_memory_cache(model=model, embeddings=embeddings)
+    _store_embedding_memory_cache(model=model, embeddings=embeddings, dimension=dimension)
     db_path = cache_db_path()
     owns_connection = conn is None
     connection = conn or _connect(db_path)

{vexor-0.22.0 → vexor-0.23.0rc1}/vexor/cli.py

@@ -31,14 +31,18 @@ from .config import (
     DEFAULT_MODEL,
     DEFAULT_PROVIDER,
     DEFAULT_RERANK,
+    DEFAULT_VOYAGE_MODEL,
+    DIMENSION_SUPPORTED_MODELS,
     SUPPORTED_EXTRACT_BACKENDS,
     SUPPORTED_PROVIDERS,
     SUPPORTED_RERANKERS,
     flashrank_cache_dir,
+    get_supported_dimensions,
     load_config,
     normalize_remote_rerank_url,
     resolve_remote_rerank_api_key,
     resolve_default_model,
+    supports_dimensions,
 )
 from .modes import available_modes, get_strategy
 from .services.cache_service import is_cache_current, load_index_metadata_safe
@@ -454,6 +458,7 @@ def search(
         rerank=rerank,
         flashrank_model=flashrank_model,
         remote_rerank=remote_rerank,
+        embedding_dimensions=config.embedding_dimensions,
     )
     if output_format == SearchOutputFormat.rich:
         if no_cache:
@@ -488,7 +493,7 @@ def search(
         else:
             typer.echo(message, err=True)
         raise typer.Exit(code=1)
-    except RuntimeError as exc:
+    except (RuntimeError, ValueError) as exc:
         if output_format == SearchOutputFormat.rich:
             console.print(_styled(str(exc), Styles.ERROR))
         else:
@@ -688,8 +693,9 @@ def index(
             local_cuda=bool(config.local_cuda),
             exclude_patterns=normalized_excludes,
             extensions=normalized_exts,
+            embedding_dimensions=config.embedding_dimensions,
         )
-    except RuntimeError as exc:
+    except (RuntimeError, ValueError) as exc:
         console.print(_styled(str(exc), Styles.ERROR))
         raise typer.Exit(code=1)
     if result.status == IndexStatus.EMPTY:
@@ -768,6 +774,16 @@ def config(
         "--clear-base-url",
         help=Messages.HELP_CLEAR_BASE_URL,
     ),
+    set_embedding_dimensions_option: int | None = typer.Option(
+        None,
+        "--set-embedding-dimensions",
+        help=Messages.HELP_SET_EMBEDDING_DIMENSIONS,
+    ),
+    clear_embedding_dimensions: bool = typer.Option(
+        False,
+        "--clear-embedding-dimensions",
+        help=Messages.HELP_CLEAR_EMBEDDING_DIMENSIONS,
+    ),
     set_auto_index_option: str | None = typer.Option(
         None,
         "--set-auto-index",
@@ -989,6 +1005,33 @@ def config(
         except ValueError as exc:
             raise typer.BadParameter(str(exc)) from exc
 
+    effective_embedding_dimensions = set_embedding_dimensions_option
+    effective_clear_embedding_dimensions = clear_embedding_dimensions
+    if effective_embedding_dimensions == 0:
+        effective_embedding_dimensions = None
+        effective_clear_embedding_dimensions = True
+
+    # Validate embedding dimensions if set
+    if effective_embedding_dimensions is not None:
+        if effective_embedding_dimensions < 0:
+            raise typer.BadParameter(
+                f"--set-embedding-dimensions must be non-negative, got {effective_embedding_dimensions}"
+            )
+        if effective_embedding_dimensions > 0:
+            # Resolve effective model from provider + model to account for provider defaults
+            effective_model = resolve_default_model(pending_provider, pending_model)
+            if not supports_dimensions(effective_model):
+                raise typer.BadParameter(
+                    f"Model '{effective_model}' does not support custom dimensions. "
+                    f"Supported model names/prefixes: {', '.join(DIMENSION_SUPPORTED_MODELS.keys())}"
+                )
+            supported = get_supported_dimensions(effective_model)
+            if supported and effective_embedding_dimensions not in supported:
+                raise typer.BadParameter(
+                    f"Dimension {effective_embedding_dimensions} is not supported for model '{effective_model}'. "
+                    f"Supported dimensions: {supported}"
+                )
+
     updates = apply_config_updates(
         api_key=set_api_key_option,
         clear_api_key=clear_api_key,
@@ -1007,6 +1050,8 @@ def config(
         remote_rerank_model=set_remote_rerank_model_option,
         remote_rerank_api_key=set_remote_rerank_api_key_option,
         clear_remote_rerank=clear_remote_rerank,
+        embedding_dimensions=effective_embedding_dimensions,
+        clear_embedding_dimensions=effective_clear_embedding_dimensions,
     )
 
     if updates.api_key_set:
@@ -1109,6 +1154,17 @@ def config(
         console.print(_styled(Messages.INFO_REMOTE_RERANK_API_KEY_SET, Styles.SUCCESS))
     if updates.remote_rerank_cleared and clear_remote_rerank:
         console.print(_styled(Messages.INFO_REMOTE_RERANK_CLEARED, Styles.SUCCESS))
+    if updates.embedding_dimensions_set and effective_embedding_dimensions is not None:
+        console.print(
+            _styled(
+                Messages.INFO_EMBEDDING_DIMENSIONS_SET.format(
+                    value=effective_embedding_dimensions
+                ),
+                Styles.SUCCESS,
+            )
+        )
+    if updates.embedding_dimensions_cleared:
+        console.print(_styled(Messages.INFO_EMBEDDING_DIMENSIONS_CLEARED, Styles.SUCCESS))
 
     if clear_flashrank:
         cache_dir = flashrank_cache_dir(create=False)
@@ -1188,6 +1244,7 @@ def config(
                     api="yes" if cfg.api_key else "no",
                     provider=provider,
                     model=resolve_default_model(provider, cfg.model),
+                    embedding_dimensions=cfg.embedding_dimensions if cfg.embedding_dimensions else "default",
                     batch=cfg.batch_size if cfg.batch_size is not None else DEFAULT_BATCH_SIZE,
                     concurrency=cfg.embed_concurrency,
                     extract_concurrency=cfg.extract_concurrency,