vexor 0.2.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

vexor/config.py

@@ -12,7 +12,11 @@ CONFIG_DIR = Path(os.path.expanduser("~")) / ".vexor"
 CONFIG_FILE = CONFIG_DIR / "config.json"
 DEFAULT_MODEL = "gemini-embedding-001"
 DEFAULT_BATCH_SIZE = 0
-ENV_API_KEY = "GOOGLE_GENAI_API_KEY"
+DEFAULT_PROVIDER = "gemini"
+SUPPORTED_PROVIDERS: tuple[str, ...] = (DEFAULT_PROVIDER, "openai")
+ENV_API_KEY = "VEXOR_API_KEY"
+LEGACY_GEMINI_ENV = "GOOGLE_GENAI_API_KEY"
+OPENAI_ENV = "OPENAI_API_KEY"
 
 
 @dataclass
@@ -20,6 +24,8 @@ class Config:
     api_key: str | None = None
     model: str = DEFAULT_MODEL
     batch_size: int = DEFAULT_BATCH_SIZE
+    provider: str = DEFAULT_PROVIDER
+    base_url: str | None = None
 
 
 def load_config() -> Config:
@@ -30,6 +36,8 @@ def load_config() -> Config:
         api_key=raw.get("api_key") or None,
         model=raw.get("model") or DEFAULT_MODEL,
         batch_size=int(raw.get("batch_size", DEFAULT_BATCH_SIZE)),
+        provider=raw.get("provider") or DEFAULT_PROVIDER,
+        base_url=raw.get("base_url") or None,
     )
 
 
@@ -41,6 +49,10 @@ def save_config(config: Config) -> None:
     if config.model:
         data["model"] = config.model
     data["batch_size"] = config.batch_size
+    if config.provider:
+        data["provider"] = config.provider
+    if config.base_url:
+        data["base_url"] = config.base_url
     CONFIG_FILE.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
 
 
@@ -60,3 +72,35 @@ def set_batch_size(value: int) -> None:
     config = load_config()
     config.batch_size = value
     save_config(config)
+
+
+def set_provider(value: str) -> None:
+    config = load_config()
+    config.provider = value
+    save_config(config)
+
+
+def set_base_url(value: str | None) -> None:
+    config = load_config()
+    config.base_url = value
+    save_config(config)
+
+
+def resolve_api_key(configured: str | None, provider: str) -> str | None:
+    """Return the first available API key from config or environment."""
+
+    if configured:
+        return configured
+    general = os.getenv(ENV_API_KEY)
+    if general:
+        return general
+    normalized = (provider or DEFAULT_PROVIDER).lower()
+    if normalized == "gemini":
+        legacy = os.getenv(LEGACY_GEMINI_ENV)
+        if legacy:
+            return legacy
+    if normalized == "openai":
+        openai_key = os.getenv(OPENAI_ENV)
+        if openai_key:
+            return openai_key
+    return None

vexor/modes.py

@@ -0,0 +1,81 @@
+"""Index mode registry and strategy helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Protocol, Sequence
+
+from .services.content_extract_service import extract_head
+
+PREVIEW_CHAR_LIMIT = 160
+
+
+@dataclass(slots=True)
+class ModePayload:
+    label: str
+    preview: str | None
+
+
+class IndexModeStrategy(Protocol):
+    name: str
+
+    def payloads_for_files(self, files: Sequence[Path]) -> list[ModePayload]:
+        raise NotImplementedError
+
+    def payload_for_file(self, file: Path) -> ModePayload:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True, slots=True)
+class NameStrategy(IndexModeStrategy):
+    name: str = "name"
+
+    def payloads_for_files(self, files: Sequence[Path]) -> list[ModePayload]:
+        return [self.payload_for_file(file) for file in files]
+
+    def payload_for_file(self, file: Path) -> ModePayload:
+        label = file.name.replace("_", " ")
+        preview = file.name
+        return ModePayload(label=label, preview=preview)
+
+
+@dataclass(frozen=True, slots=True)
+class HeadStrategy(IndexModeStrategy):
+    name: str = "head"
+    fallback: NameStrategy = NameStrategy()
+
+    def payloads_for_files(self, files: Sequence[Path]) -> list[ModePayload]:
+        return [self.payload_for_file(file) for file in files]
+
+    def payload_for_file(self, file: Path) -> ModePayload:
+        snippet = extract_head(file)
+        if snippet:
+            label = f"{file.name} :: {snippet}"
+            preview = _trim_preview(snippet)
+            return ModePayload(label=label, preview=preview)
+        return self.fallback.payload_for_file(file)
+
+
+_STRATEGIES: Dict[str, IndexModeStrategy] = {
+    "name": NameStrategy(),
+    "head": HeadStrategy(),
+}
+
+
+def get_strategy(mode: str) -> IndexModeStrategy:
+    try:
+        return _STRATEGIES[mode]
+    except KeyError as exc:
+        raise ValueError(f"Unsupported mode: {mode}") from exc
+
+
+def available_modes() -> list[str]:
+    return sorted(_STRATEGIES.keys())
+
+
+def _trim_preview(text: str, limit: int = PREVIEW_CHAR_LIMIT) -> str:
+    stripped = text.strip()
+    if len(stripped) <= limit:
+        return stripped
+    return stripped[: limit - 1].rstrip() + "…"

vexor/providers/__init__.py

@@ -0,0 +1,3 @@
+"""Embedding backend implementations for Vexor."""
+
+__all__ = ["gemini", "openai"]

vexor/providers/gemini.py

@@ -0,0 +1,74 @@
+"""Gemini-backed embedding backend for Vexor."""
+
+from __future__ import annotations
+
+from typing import Iterator, Sequence
+
+import numpy as np
+from dotenv import load_dotenv
+from google import genai
+from google.genai import errors as genai_errors
+from google.genai import types as genai_types
+
+from ..config import DEFAULT_MODEL
+from ..text import Messages
+
+
+class GeminiEmbeddingBackend:
+    """Embedding backend that calls the Gemini API via google-genai."""
+
+    def __init__(
+        self,
+        *,
+        model_name: str = DEFAULT_MODEL,
+        api_key: str | None = None,
+        chunk_size: int | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        load_dotenv()
+        self.model_name = model_name
+        self.chunk_size = chunk_size if chunk_size and chunk_size > 0 else None
+        self.api_key = api_key
+        if not self.api_key or self.api_key.strip().lower() == "your_api_key_here":
+            raise RuntimeError(Messages.ERROR_API_KEY_MISSING)
+        client_kwargs: dict[str, object] = {"api_key": self.api_key}
+        if base_url:
+            client_kwargs["http_options"] = genai_types.HttpOptions(base_url=base_url)
+        self._client = genai.Client(**client_kwargs)
+
+    def embed(self, texts: Sequence[str]) -> np.ndarray:
+        if not texts:
+            return np.empty((0, 0), dtype=np.float32)
+        vectors: list[np.ndarray] = []
+        for chunk in _chunk(texts, self.chunk_size):
+            try:
+                response = self._client.models.embed_content(
+                    model=self.model_name,
+                    contents=list(chunk),
+                )
+            except genai_errors.ClientError as exc:
+                raise RuntimeError(_format_genai_error(exc)) from exc
+            embeddings = getattr(response, "embeddings", None)
+            if not embeddings:
+                raise RuntimeError(Messages.ERROR_NO_EMBEDDINGS)
+            for embedding in embeddings:
+                values = getattr(embedding, "values", None) or getattr(
+                    embedding, "value", None
+                )
+                vectors.append(np.asarray(values, dtype=np.float32))
+        return np.vstack(vectors)
+
+
+def _chunk(items: Sequence[str], size: int | None) -> Iterator[Sequence[str]]:
+    if size is None or size <= 0:
+        yield items
+        return
+    for idx in range(0, len(items), size):
+        yield items[idx : idx + size]
+
+
+def _format_genai_error(exc: genai_errors.ClientError) -> str:
+    message = getattr(exc, "message", None) or str(exc)
+    if "API key" in message:
+        return Messages.ERROR_API_KEY_INVALID
+    return f"{Messages.ERROR_GENAI_PREFIX}{message}"

vexor/providers/openai.py

@@ -0,0 +1,69 @@
+"""OpenAI-backed embedding backend for Vexor."""
+
+from __future__ import annotations
+
+from typing import Iterator, Sequence
+
+import numpy as np
+from dotenv import load_dotenv
+from openai import OpenAI
+
+from ..text import Messages
+
+
+class OpenAIEmbeddingBackend:
+    """Embedding backend that calls OpenAI's embeddings API."""
+
+    def __init__(
+        self,
+        *,
+        model_name: str,
+        api_key: str | None,
+        chunk_size: int | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        load_dotenv()
+        self.model_name = model_name
+        self.chunk_size = chunk_size if chunk_size and chunk_size > 0 else None
+        self.api_key = api_key
+        if not self.api_key:
+            raise RuntimeError(Messages.ERROR_API_KEY_MISSING)
+        client_kwargs: dict[str, object] = {"api_key": self.api_key}
+        if base_url:
+            client_kwargs["base_url"] = base_url.rstrip("/")
+        self._client = OpenAI(**client_kwargs)
+
+    def embed(self, texts: Sequence[str]) -> np.ndarray:
+        if not texts:
+            return np.empty((0, 0), dtype=np.float32)
+        vectors: list[np.ndarray] = []
+        for chunk in _chunk(texts, self.chunk_size):
+            try:
+                response = self._client.embeddings.create(
+                    model=self.model_name,
+                    input=list(chunk),
+                )
+            except Exception as exc:  # pragma: no cover - API client variations
+                raise RuntimeError(_format_openai_error(exc)) from exc
+            data = getattr(response, "data", None) or []
+            if not data:
+                raise RuntimeError(Messages.ERROR_NO_EMBEDDINGS)
+            for item in data:
+                embedding = getattr(item, "embedding", None)
+                if embedding is None:
+                    continue
+                vectors.append(np.asarray(embedding, dtype=np.float32))
+        return np.vstack(vectors)
+
+
+def _chunk(items: Sequence[str], size: int | None) -> Iterator[Sequence[str]]:
+    if size is None or size <= 0:
+        yield items
+        return
+    for idx in range(0, len(items), size):
+        yield items[idx : idx + size]
+
+
+def _format_openai_error(exc: Exception) -> str:
+    message = getattr(exc, "message", None) or str(exc)
+    return f"{Messages.ERROR_OPENAI_PREFIX}{message}"

vexor/search.py

@@ -1,19 +1,17 @@
-"""Semantic search helpers backed by the Google Gemini embedding API."""
+"""Semantic search helpers backed by pluggable embedding backends."""
 
 from __future__ import annotations
 
-import os
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Iterator, List, Protocol, Sequence
+from typing import List, Protocol, Sequence
 
 import numpy as np
-from dotenv import load_dotenv
-from google import genai
-from google.genai import errors as genai_errors
 from sklearn.metrics.pairwise import cosine_similarity
 
-from .config import DEFAULT_MODEL, ENV_API_KEY, load_config
+from .config import DEFAULT_MODEL, DEFAULT_PROVIDER, SUPPORTED_PROVIDERS, resolve_api_key
+from .providers.gemini import GeminiEmbeddingBackend
+from .providers.openai import OpenAIEmbeddingBackend
 from .text import Messages
 
 
@@ -23,6 +21,7 @@ class SearchResult:
 
     path: Path
     score: float
+    preview: str | None = None
 
 
 class EmbeddingBackend(Protocol):
@@ -33,50 +32,6 @@ class EmbeddingBackend(Protocol):
         raise NotImplementedError  # pragma: no cover
 
 
-class GeminiEmbeddingBackend:
-    """Embedding backend that calls the Gemini API via google-genai."""
-
-    def __init__(
-        self,
-        *,
-        model_name: str = DEFAULT_MODEL,
-        api_key: str | None = None,
-        chunk_size: int | None = None,
-    ) -> None:
-        load_dotenv()
-        config = load_config()
-        self.model_name = model_name
-        self.chunk_size = chunk_size if chunk_size and chunk_size > 0 else None
-        env_key = os.getenv(ENV_API_KEY)
-        configured_key = getattr(config, "api_key", None)
-        self.api_key = api_key or configured_key or env_key
-        if not self.api_key or self.api_key.strip().lower() == "your_api_key_here":
-            raise RuntimeError(Messages.ERROR_API_KEY_MISSING)
-        self._client = genai.Client(api_key=self.api_key)
-
-    def embed(self, texts: Sequence[str]) -> np.ndarray:
-        if not texts:
-            return np.empty((0, 0), dtype=np.float32)
-        vectors: list[np.ndarray] = []
-        for chunk in _chunk(texts, self.chunk_size):
-            try:
-                response = self._client.models.embed_content(
-                    model=self.model_name,
-                    contents=list(chunk),
-                )
-            except genai_errors.ClientError as exc:
-                raise RuntimeError(_format_genai_error(exc)) from exc
-            embeddings = getattr(response, "embeddings", None)
-            if not embeddings:
-                raise RuntimeError(Messages.ERROR_NO_EMBEDDINGS)
-            for embedding in embeddings:
-                values = getattr(embedding, "values", None) or getattr(
-                    embedding, "value", None
-                )
-                vectors.append(np.asarray(values, dtype=np.float32))
-        return np.vstack(vectors)
-
-
 class VexorSearcher:
     """Encapsulates embedding generation and similarity computation."""
 
@@ -86,13 +41,20 @@ class VexorSearcher:
         *,
         backend: EmbeddingBackend | None = None,
         batch_size: int = 0,
+        provider: str = DEFAULT_PROVIDER,
+        base_url: str | None = None,
+        api_key: str | None = None,
     ) -> None:
         self.model_name = model_name
         self.batch_size = max(batch_size, 0)
-        self._backend = backend or GeminiEmbeddingBackend(
-            model_name=model_name, chunk_size=self.batch_size
-        )
-        self._device = f"{self.model_name} via Gemini API"
+        self.provider = (provider or DEFAULT_PROVIDER).lower()
+        self.base_url = base_url
+        self.api_key = resolve_api_key(api_key, self.provider)
+        if backend is not None:
+            self._backend = backend
+            self._device = getattr(backend, "device", "Custom embedding backend")
+        else:
+            self._backend = self._create_backend()
 
     @property
     def device(self) -> str:
@@ -136,17 +98,24 @@ class VexorSearcher:
         """Return the text representation of a file path for embedding."""
         return path.name.replace("_", " ")
 
-
-def _chunk(items: Sequence[str], size: int | None) -> Iterator[Sequence[str]]:
-    if size is None or size <= 0:
-        yield items
-        return
-    for idx in range(0, len(items), size):
-        yield items[idx : idx + size]
-
-
-def _format_genai_error(exc: genai_errors.ClientError) -> str:
-    message = getattr(exc, "message", None) or str(exc)
-    if "API key" in message:
-        return Messages.ERROR_API_KEY_INVALID
-    return f"{Messages.ERROR_GENAI_PREFIX}{message}"
+    def _create_backend(self) -> EmbeddingBackend:
+        if self.provider == "gemini":
+            self._device = f"{self.model_name} via Gemini API"
+            return GeminiEmbeddingBackend(
+                model_name=self.model_name,
+                chunk_size=self.batch_size,
+                base_url=self.base_url,
+                api_key=self.api_key,
+            )
+        if self.provider == "openai":
+            self._device = f"{self.model_name} via OpenAI API"
+            return OpenAIEmbeddingBackend(
+                model_name=self.model_name,
+                chunk_size=self.batch_size,
+                base_url=self.base_url,
+                api_key=self.api_key,
+            )
+        allowed = ", ".join(SUPPORTED_PROVIDERS)
+        raise RuntimeError(
+            Messages.ERROR_PROVIDER_INVALID.format(value=self.provider, allowed=allowed)
+        )

vexor/services/__init__.py

@@ -0,0 +1,9 @@
+"""Higher level service helpers used by the CLI layer."""
+
+__all__ = [
+    "cache_service",
+    "config_service",
+    "index_service",
+    "search_service",
+]
+

vexor/services/cache_service.py

@@ -0,0 +1,39 @@
+"""Shared helpers for interacting with cached index metadata."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Sequence
+
+def is_cache_current(
+    root: Path,
+    include_hidden: bool,
+    cached_files: Sequence[dict],
+    *,
+    recursive: bool,
+    current_files=None,
+) -> bool:
+    """Return True if cached metadata matches the current directory snapshot."""
+
+    if not cached_files:
+        return False
+    from ..cache import compare_snapshot  # local import avoids eager heavy deps
+
+    return compare_snapshot(
+        root,
+        include_hidden,
+        cached_files,
+        recursive=recursive,
+        current_files=current_files,
+    )
+
+
+def load_index_metadata_safe(root: Path, model: str, include_hidden: bool, mode: str, recursive: bool):
+    """Load index metadata when present, returning None if missing."""
+
+    from ..cache import load_index  # local import avoids eager heavy deps
+
+    try:
+        return load_index(root, model, include_hidden, mode, recursive)
+    except FileNotFoundError:
+        return None

vexor/services/config_service.py

@@ -0,0 +1,83 @@
+"""Logic helpers for the `vexor config` command."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..config import (
+    Config,
+    load_config,
+    set_api_key,
+    set_base_url,
+    set_batch_size,
+    set_model,
+    set_provider,
+)
+
+
+@dataclass(slots=True)
+class ConfigUpdateResult:
+    api_key_set: bool = False
+    api_key_cleared: bool = False
+    model_set: bool = False
+    batch_size_set: bool = False
+    provider_set: bool = False
+    base_url_set: bool = False
+    base_url_cleared: bool = False
+
+    @property
+    def changed(self) -> bool:
+        return any(
+            (
+                self.api_key_set,
+                self.api_key_cleared,
+                self.model_set,
+                self.batch_size_set,
+                self.provider_set,
+                self.base_url_set,
+                self.base_url_cleared,
+            )
+        )
+
+
+def apply_config_updates(
+    *,
+    api_key: str | None = None,
+    clear_api_key: bool = False,
+    model: str | None = None,
+    batch_size: int | None = None,
+    provider: str | None = None,
+    base_url: str | None = None,
+    clear_base_url: bool = False,
+) -> ConfigUpdateResult:
+    """Apply config mutations and report which fields were updated."""
+
+    result = ConfigUpdateResult()
+    if api_key is not None:
+        set_api_key(api_key)
+        result.api_key_set = True
+    if clear_api_key:
+        set_api_key(None)
+        result.api_key_cleared = True
+    if model is not None:
+        set_model(model)
+        result.model_set = True
+    if batch_size is not None:
+        set_batch_size(batch_size)
+        result.batch_size_set = True
+    if provider is not None:
+        set_provider(provider)
+        result.provider_set = True
+    if base_url is not None:
+        set_base_url(base_url)
+        result.base_url_set = True
+    if clear_base_url:
+        set_base_url(None)
+        result.base_url_cleared = True
+    return result
+
+
+def get_config_snapshot() -> Config:
+    """Return the current configuration dataclass."""
+
+    return load_config()