vexor 0.2.0__py3-none-any.whl

vexor/__init__.py

@@ -0,0 +1,12 @@
+"""Vexor package initialization."""
+
+from __future__ import annotations
+
+__all__ = ["__version__", "get_version"]
+
+__version__ = "0.2.0"
+
+
+def get_version() -> str:
+    """Return the current package version."""
+    return __version__

vexor/__main__.py

@@ -0,0 +1,18 @@
+"""Entry point for `python -m vexor` and frozen builds."""
+
+from __future__ import annotations
+
+try:
+    # Normal package execution path
+    from .cli import run
+except ImportError:  # pragma: no cover - happens in frozen single-file builds
+    from vexor.cli import run  # type: ignore[import]
+
+
+def main() -> None:
+    """Execute the Typer application."""
+    run()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vexor/cache.py

@@ -0,0 +1,286 @@
+"""Index cache helpers for Vexor backed by SQLite."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Sequence
+
+import numpy as np
+
+from .utils import collect_files
+
+CACHE_DIR = Path(os.path.expanduser("~")) / ".vexor"
+CACHE_VERSION = 1
+DB_FILENAME = "index.db"
+
+
+def _cache_key(root: Path, include_hidden: bool) -> str:
+    digest = hashlib.sha1(
+        f"{root.resolve()}|hidden={include_hidden}".encode("utf-8")
+    ).hexdigest()
+    return digest
+
+
+def ensure_cache_dir() -> Path:
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    return CACHE_DIR
+
+
+def cache_file(root: Path, model: str, include_hidden: bool) -> Path:  # pragma: no cover - kept for API parity
+    """Return the on-disk cache artifact path (single SQLite DB)."""
+    ensure_cache_dir()
+    return CACHE_DIR / DB_FILENAME
+
+
+def _connect(db_path: Path) -> sqlite3.Connection:
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON;")
+    return conn
+
+
+def _ensure_schema(conn: sqlite3.Connection) -> None:
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS index_metadata (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            cache_key TEXT NOT NULL,
+            root_path TEXT NOT NULL,
+            model TEXT NOT NULL,
+            include_hidden INTEGER NOT NULL,
+            dimension INTEGER NOT NULL,
+            version INTEGER NOT NULL,
+            generated_at TEXT NOT NULL,
+            UNIQUE(cache_key, model)
+        );
+
+        CREATE TABLE IF NOT EXISTS indexed_file (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            index_id INTEGER NOT NULL REFERENCES index_metadata(id) ON DELETE CASCADE,
+            rel_path TEXT NOT NULL,
+            abs_path TEXT NOT NULL,
+            size_bytes INTEGER NOT NULL,
+            mtime REAL NOT NULL,
+            position INTEGER NOT NULL,
+            UNIQUE(index_id, rel_path)
+        );
+
+        CREATE TABLE IF NOT EXISTS file_embedding (
+            file_id INTEGER PRIMARY KEY REFERENCES indexed_file(id) ON DELETE CASCADE,
+            vector_blob BLOB NOT NULL
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_indexed_file_order
+            ON indexed_file(index_id, position);
+        """
+    )
+
+
+def store_index(
+    *,
+    root: Path,
+    model: str,
+    include_hidden: bool,
+    files: Sequence[Path],
+    embeddings: np.ndarray,
+) -> Path:
+    db_path = cache_file(root, model, include_hidden)
+    conn = _connect(db_path)
+    try:
+        _ensure_schema(conn)
+        key = _cache_key(root, include_hidden)
+        generated_at = datetime.now(timezone.utc).isoformat()
+        dimension = int(embeddings.shape[1] if embeddings.size else 0)
+        include_flag = 1 if include_hidden else 0
+
+        with conn:
+            conn.execute(
+                "DELETE FROM index_metadata WHERE cache_key = ? AND model = ?",
+                (key, model),
+            )
+            cursor = conn.execute(
+                """
+                INSERT INTO index_metadata (
+                    cache_key,
+                    root_path,
+                    model,
+                    include_hidden,
+                    dimension,
+                    version,
+                    generated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?)
+                """,
+                (key, str(root), model, include_flag, dimension, CACHE_VERSION, generated_at),
+            )
+            index_id = cursor.lastrowid
+
+            for position, file in enumerate(files):
+                stat = file.stat()
+                try:
+                    rel_path = file.relative_to(root)
+                except ValueError:
+                    rel_path = file
+                file_cursor = conn.execute(
+                    """
+                    INSERT INTO indexed_file (
+                        index_id,
+                        rel_path,
+                        abs_path,
+                        size_bytes,
+                        mtime,
+                        position
+                    ) VALUES (?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        index_id,
+                        str(rel_path),
+                        str(file),
+                        stat.st_size,
+                        stat.st_mtime,
+                        position,
+                    ),
+                )
+                vector_blob = embeddings[position].astype(np.float32).tobytes()
+                conn.execute(
+                    "INSERT INTO file_embedding (file_id, vector_blob) VALUES (?, ?)",
+                    (file_cursor.lastrowid, vector_blob),
+                )
+
+        return db_path
+    finally:
+        conn.close()
+
+
+def load_index(root: Path, model: str, include_hidden: bool) -> dict:
+    db_path = cache_file(root, model, include_hidden)
+    if not db_path.exists():
+        raise FileNotFoundError(db_path)
+
+    conn = _connect(db_path)
+    try:
+        _ensure_schema(conn)
+        key = _cache_key(root, include_hidden)
+        include_flag = 1 if include_hidden else 0
+        meta = conn.execute(
+            """
+            SELECT id, root_path, model, include_hidden, dimension, version, generated_at
+            FROM index_metadata
+            WHERE cache_key = ? AND model = ? AND include_hidden = ?
+            """,
+            (key, model, include_flag),
+        ).fetchone()
+        if meta is None:
+            raise FileNotFoundError(db_path)
+
+        files = conn.execute(
+            """
+            SELECT f.rel_path, f.abs_path, f.size_bytes, f.mtime, e.vector_blob
+            FROM indexed_file AS f
+            JOIN file_embedding AS e ON e.file_id = f.id
+            WHERE f.index_id = ?
+            ORDER BY f.position ASC
+            """,
+            (meta["id"],),
+        ).fetchall()
+
+        serialized_files = []
+        for row in files:
+            vector = np.frombuffer(row["vector_blob"], dtype=np.float32)
+            serialized_files.append(
+                {
+                    "path": row["rel_path"],
+                    "absolute": row["abs_path"],
+                    "mtime": row["mtime"],
+                    "size": row["size_bytes"],
+                    "embedding": vector.tolist(),
+                }
+            )
+
+        return {
+            "version": meta["version"],
+            "generated_at": meta["generated_at"],
+            "root": meta["root_path"],
+            "model": meta["model"],
+            "include_hidden": bool(meta["include_hidden"]),
+            "dimension": meta["dimension"],
+            "files": serialized_files,
+        }
+    finally:
+        conn.close()
+
+
+def load_index_vectors(root: Path, model: str, include_hidden: bool):
+    data = load_index(root, model, include_hidden)
+    files = data.get("files", [])
+    paths = [root / Path(entry["path"]) for entry in files]
+    embeddings = np.asarray([entry["embedding"] for entry in files], dtype=np.float32)
+    return paths, embeddings, data
+
+
+def clear_index(root: Path, include_hidden: bool, model: str | None = None) -> int:
+    """Remove cached index entries for *root* (optionally filtered by *model*)."""
+    db_path = cache_file(root, model or "_", include_hidden)
+    if not db_path.exists():
+        return 0
+
+    conn = _connect(db_path)
+    try:
+        _ensure_schema(conn)
+        key = _cache_key(root, include_hidden)
+        if model is None:
+            query = "DELETE FROM index_metadata WHERE cache_key = ?"
+            params = (key,)
+        else:
+            query = "DELETE FROM index_metadata WHERE cache_key = ? AND model = ?"
+            params = (key, model)
+        with conn:
+            cursor = conn.execute(query, params)
+        return cursor.rowcount
+    finally:
+        conn.close()
+
+
+def compare_snapshot(
+    root: Path,
+    include_hidden: bool,
+    cached_files: Sequence[dict],
+    current_files: Sequence[Path] | None = None,
+) -> bool:
+    """Return True if the current filesystem matches the cached snapshot."""
+    if current_files is None:
+        current_files = collect_files(root, include_hidden=include_hidden)
+    if len(current_files) != len(cached_files):
+        return False
+    cached_map = {
+        entry["path"]: (entry["mtime"], entry.get("size"))
+        for entry in cached_files
+    }
+    for file in current_files:
+        rel = _relative_path(file, root)
+        data = cached_map.get(rel)
+        if data is None:
+            return False
+        cached_mtime, cached_size = data
+        stat = file.stat()
+        current_mtime = stat.st_mtime
+        current_size = stat.st_size
+        # allow drift due to filesystem precision (approx 0.5s on some platforms)
+        if abs(current_mtime - cached_mtime) > 5e-1:
+            if cached_size is not None and cached_size == current_size:
+                continue
+            return False
+        if cached_size is not None and cached_size != current_size:
+            return False
+    return True
+
+
+def _relative_path(path: Path, root: Path) -> str:
+    try:
+        rel = path.relative_to(root)
+    except ValueError:
+        rel = path
+    return str(rel)

vexor/cli.py

@@ -0,0 +1,466 @@
+"""Command line interface for Vexor."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+import shutil
+import re
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+from .config import (
+    DEFAULT_BATCH_SIZE,
+    DEFAULT_MODEL,
+    load_config,
+    set_api_key,
+    set_batch_size,
+    set_model,
+)
+from .text import Messages, Styles
+from .utils import collect_files, resolve_directory, format_path, ensure_positive
+
+REMOTE_VERSION_URL = "https://raw.githubusercontent.com/scarletkc/vexor/refs/heads/main/vexor/__init__.py"
+PROJECT_URL = "https://github.com/scarletkc/vexor"
+PYPI_URL = "https://pypi.org/project/vexor/"
+
+console = Console()
+app = typer.Typer(
+    help=Messages.APP_HELP,
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+@dataclass(slots=True)
+class DisplayResult:
+    path: Path
+    score: float
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"Vexor v{__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-v",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    )
+) -> None:
+    """Global Typer callback for shared options."""
+    return None
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help=Messages.HELP_QUERY),
+    path: Path = typer.Option(
+        Path.cwd(),
+        "--path",
+        "-p",
+        help=Messages.HELP_SEARCH_PATH,
+    ),
+    top: int = typer.Option(5, "--top", "-k", help=Messages.HELP_SEARCH_TOP),
+    include_hidden: bool = typer.Option(
+        False,
+        "--include-hidden",
+        help=Messages.HELP_INCLUDE_HIDDEN,
+    ),
+) -> None:
+    """Run the semantic search using a cached index."""
+    config = load_config()
+    model_name = config.model or DEFAULT_MODEL
+    batch_size = config.batch_size if config.batch_size is not None else DEFAULT_BATCH_SIZE
+
+    clean_query = query.strip()
+    if not clean_query:
+        console.print(_styled(Messages.ERROR_EMPTY_QUERY, Styles.ERROR))
+        raise typer.Exit(code=1)
+    try:
+        ensure_positive(top, "top")
+    except ValueError as exc:  # pragma: no cover - validated by Typer
+        raise typer.BadParameter(str(exc), param_name="top") from exc
+
+    directory = resolve_directory(path)
+    console.print(_styled(Messages.INFO_SEARCH_RUNNING.format(path=directory), Styles.INFO))
+    try:
+        cached_paths, file_vectors, meta = _load_index(directory, model_name, include_hidden)
+    except FileNotFoundError:
+        console.print(
+            _styled(Messages.ERROR_INDEX_MISSING.format(path=directory), Styles.ERROR)
+        )
+        raise typer.Exit(code=1)
+
+    _warn_if_stale(directory, include_hidden, meta.get("files", []))
+
+    if not cached_paths:
+        console.print(_styled(Messages.INFO_INDEX_EMPTY, Styles.WARNING))
+        raise typer.Exit(code=0)
+
+    searcher = _create_searcher(model_name=model_name, batch_size=batch_size)
+    try:
+        query_vector = searcher.embed_texts([clean_query])[0]
+    except RuntimeError as exc:
+        console.print(_styled(str(exc), Styles.ERROR))
+        raise typer.Exit(code=1)
+
+    from sklearn.metrics.pairwise import cosine_similarity  # local import
+
+    similarities = cosine_similarity(
+        query_vector.reshape(1, -1), file_vectors
+    )[0]
+    scored = [
+        DisplayResult(path=path, score=float(score))
+        for path, score in zip(cached_paths, similarities)
+    ]
+    scored.sort(key=lambda item: item.score, reverse=True)
+    results = scored[:top]
+
+    if not results:
+        console.print(_styled(Messages.INFO_NO_RESULTS, Styles.WARNING))
+        raise typer.Exit(code=0)
+
+    _render_results(results, directory, searcher.device)
+
+
+@app.command()
+def index(
+    path: Path = typer.Option(
+        Path.cwd(),
+        "--path",
+        "-p",
+        help=Messages.HELP_INDEX_PATH,
+    ),
+    include_hidden: bool = typer.Option(
+        False,
+        "--include-hidden",
+        help=Messages.HELP_INDEX_INCLUDE,
+    ),
+    clear: bool = typer.Option(
+        False,
+        "--clear",
+        help=Messages.HELP_INDEX_CLEAR,
+    ),
+) -> None:
+    """Create or refresh the cached index for the given directory."""
+    config = load_config()
+    model_name = config.model or DEFAULT_MODEL
+    batch_size = config.batch_size if config.batch_size is not None else DEFAULT_BATCH_SIZE
+
+    directory = resolve_directory(path)
+    if clear:
+        removed = _clear_index_cache(directory, include_hidden)
+        if removed:
+            plural = "ies" if removed > 1 else "y"
+            console.print(
+                _styled(
+                    Messages.INFO_INDEX_CLEARED.format(
+                        path=directory,
+                        count=removed,
+                        plural=plural,
+                    ),
+                    Styles.SUCCESS,
+                )
+            )
+        else:
+            console.print(
+                _styled(
+                    Messages.INFO_INDEX_CLEAR_NONE.format(path=directory),
+                    Styles.INFO,
+                )
+            )
+        return
+
+    console.print(_styled(Messages.INFO_INDEX_RUNNING.format(path=directory), Styles.INFO))
+    files = collect_files(directory, include_hidden=include_hidden)
+    if not files:
+        console.print(_styled(Messages.INFO_NO_FILES, Styles.WARNING))
+        raise typer.Exit(code=0)
+
+    existing_meta = _load_index_metadata_safe(directory, model_name, include_hidden)
+    if existing_meta:
+        cached_files = existing_meta.get("files", [])
+        if cached_files and _is_cache_current(
+            directory, include_hidden, cached_files, current_files=files
+        ):
+            console.print(
+                _styled(Messages.INFO_INDEX_UP_TO_DATE.format(path=directory), Styles.INFO)
+            )
+            return
+
+    searcher = _create_searcher(model_name=model_name, batch_size=batch_size)
+    file_labels = [_label_for_path(file) for file in files]
+    embeddings = searcher.embed_texts(file_labels)
+
+    cache_path = _store_index(
+        root=directory,
+        model=model_name,
+        include_hidden=include_hidden,
+        files=files,
+        embeddings=embeddings,
+    )
+    console.print(_styled(Messages.INFO_INDEX_SAVED.format(path=cache_path), Styles.SUCCESS))
+
+
+@app.command()
+def config(
+    set_api_key_option: str | None = typer.Option(
+        None,
+        "--set-api-key",
+        help=Messages.HELP_SET_API_KEY,
+    ),
+    clear_api_key: bool = typer.Option(
+        False,
+        "--clear-api-key",
+        help=Messages.HELP_CLEAR_API_KEY,
+    ),
+    set_model_option: str | None = typer.Option(
+        None,
+        "--set-model",
+        help=Messages.HELP_SET_MODEL,
+    ),
+    set_batch_option: int | None = typer.Option(
+        None,
+        "--set-batch-size",
+        help=Messages.HELP_SET_BATCH,
+    ),
+    show: bool = typer.Option(
+        False,
+        "--show",
+        help=Messages.HELP_SHOW_CONFIG,
+    ),
+) -> None:
+    """Manage Vexor configuration stored in ~/.vexor/config.json."""
+    changed = False
+
+    if set_api_key_option is not None:
+        set_api_key(set_api_key_option)
+        console.print(_styled(Messages.INFO_API_SAVED, Styles.SUCCESS))
+        changed = True
+    if clear_api_key:
+        set_api_key(None)
+        console.print(_styled(Messages.INFO_API_CLEARED, Styles.SUCCESS))
+        changed = True
+    if set_model_option is not None:
+        set_model(set_model_option)
+        console.print(
+            _styled(Messages.INFO_MODEL_SET.format(value=set_model_option), Styles.SUCCESS)
+        )
+        changed = True
+    if set_batch_option is not None:
+        if set_batch_option < 0:
+            raise typer.BadParameter(Messages.ERROR_BATCH_NEGATIVE)
+        set_batch_size(set_batch_option)
+        console.print(
+            _styled(Messages.INFO_BATCH_SET.format(value=set_batch_option), Styles.SUCCESS)
+        )
+        changed = True
+
+    if show or not changed:
+        cfg = load_config()
+        console.print(
+            _styled(
+                Messages.INFO_CONFIG_SUMMARY.format(
+                    api="yes" if cfg.api_key else "no",
+                    model=cfg.model or DEFAULT_MODEL,
+                    batch=cfg.batch_size if cfg.batch_size is not None else DEFAULT_BATCH_SIZE,
+                ),
+                Styles.INFO,
+            )
+        )
+
+
+@app.command()
+def doctor() -> None:
+    """Check whether the `vexor` command is available on PATH."""
+    console.print(_styled(Messages.INFO_DOCTOR_CHECKING, Styles.INFO))
+    command_path = shutil.which("vexor")
+    if command_path:
+        console.print(
+            _styled(Messages.INFO_DOCTOR_FOUND.format(path=command_path), Styles.SUCCESS)
+        )
+        return
+    console.print(_styled(Messages.ERROR_DOCTOR_MISSING, Styles.ERROR))
+    raise typer.Exit(code=1)
+
+
+@app.command()
+def update() -> None:
+    """Check whether a newer release is available online."""
+    console.print(_styled(Messages.INFO_UPDATE_CHECKING, Styles.INFO))
+    console.print(_styled(Messages.INFO_UPDATE_CURRENT.format(current=__version__), Styles.INFO))
+    try:
+        latest = _fetch_remote_version()
+    except RuntimeError as exc:
+        console.print(
+            _styled(Messages.ERROR_UPDATE_FETCH.format(reason=str(exc)), Styles.ERROR)
+        )
+        raise typer.Exit(code=1)
+
+    if _version_tuple(latest) > _version_tuple(__version__):
+        console.print(
+            _styled(
+                Messages.INFO_UPDATE_AVAILABLE.format(
+                    latest=latest,
+                    github=PROJECT_URL,
+                    pypi=PYPI_URL,
+                ),
+                Styles.WARNING,
+            )
+        )
+        return
+
+    console.print(
+        _styled(Messages.INFO_UPDATE_UP_TO_DATE.format(latest=latest), Styles.SUCCESS)
+    )
+
+
+def _render_results(results: Sequence[DisplayResult], base: Path, backend: str | None) -> None:
+    console.print(_styled(Messages.TABLE_TITLE, Styles.TITLE))
+    if backend:
+        console.print(_styled(f"{Messages.TABLE_BACKEND_PREFIX}{backend}", Styles.INFO))
+    table = Table(show_header=True, header_style=Styles.TABLE_HEADER)
+    table.add_column(Messages.TABLE_HEADER_INDEX, justify="right")
+    table.add_column(Messages.TABLE_HEADER_SIMILARITY, justify="right")
+    table.add_column(Messages.TABLE_HEADER_PATH, overflow="fold")
+    for idx, result in enumerate(results, start=1):
+        table.add_row(
+            str(idx),
+            f"{result.score:.3f}",
+            format_path(result.path, base),
+        )
+    console.print(table)
+
+
+def _create_searcher(model_name: str, batch_size: int):
+    from .search import VexorSearcher  # Local import keeps CLI startup fast
+
+    return VexorSearcher(model_name=model_name, batch_size=batch_size)
+
+
+def _label_for_path(path: Path) -> str:
+    return path.name.replace("_", " ")
+
+
+def _load_index(root: Path, model: str, include_hidden: bool):
+    from .cache import load_index_vectors  # local import
+
+    return load_index_vectors(root, model, include_hidden)
+
+
+def _load_index_metadata_safe(root: Path, model: str, include_hidden: bool):
+    from .cache import load_index  # local import
+
+    try:
+        return load_index(root, model, include_hidden)
+    except FileNotFoundError:
+        return None
+
+
+def _store_index(**kwargs):
+    from .cache import store_index  # local import
+
+    return store_index(**kwargs)
+
+
+def _clear_index_cache(root: Path, include_hidden: bool, model: str | None = None) -> int:
+    from .cache import clear_index  # local import
+
+    return clear_index(root=root, include_hidden=include_hidden, model=model)
+
+
+def _fetch_remote_version(url: str = REMOTE_VERSION_URL) -> str:
+    from urllib import request, error
+
+    try:
+        with request.urlopen(url, timeout=10) as response:
+            if response.status != 200:
+                raise RuntimeError(f"HTTP {response.status}")
+            text = response.read().decode("utf-8")
+    except error.URLError as exc:  # pragma: no cover - network error
+        raise RuntimeError(str(exc)) from exc
+
+    match = re.search(r"__version__\s*=\s*['\"]([^'\"]+)['\"]", text)
+    if not match:
+        raise RuntimeError("Version string not found")
+    return match.group(1)
+
+
+def _version_tuple(raw: str) -> tuple[int, int, int, int]:
+    raw = raw.strip()
+    release_parts: list[int] = []
+    suffix_number = 0
+
+    for piece in raw.split('.'):
+        match = re.match(r"^(\d+)", piece)
+        if not match:
+            break
+        release_parts.append(int(match.group(1)))
+        remainder = piece[match.end():]
+        if remainder:
+            suffix_match = re.match(r"[A-Za-z]+(\d+)", remainder)
+            if suffix_match:
+                suffix_number = int(suffix_match.group(1))
+            break
+        if len(release_parts) >= 4:
+            break
+
+    while len(release_parts) < 4:
+        release_parts.append(0)
+
+    if suffix_number:
+        release_parts[3] = suffix_number
+
+    return tuple(release_parts[:4])
+
+
+def _is_cache_current(
+    root: Path,
+    include_hidden: bool,
+    cached_files: Sequence[dict],
+    *,
+    current_files: Sequence[Path] | None = None,
+) -> bool:
+    if not cached_files:
+        return False
+    from .cache import compare_snapshot  # local import
+
+    return compare_snapshot(
+        root,
+        include_hidden,
+        cached_files,
+        current_files=current_files,
+    )
+
+
+def _warn_if_stale(root: Path, include_hidden: bool, cached_files: Sequence[dict]) -> None:
+    if not cached_files:
+        return
+    if not _is_cache_current(root, include_hidden, cached_files):
+        console.print(
+            _styled(Messages.WARNING_INDEX_STALE.format(path=root), Styles.WARNING)
+        )
+
+
+def _styled(text: str, style: str) -> str:
+    return f"[{style}]{text}[/{style}]"
+
+
+def run(argv: list[str] | None = None) -> None:
+    """Entry point wrapper allowing optional argument override."""
+    if argv is None:
+        app()
+    else:
+        app(args=list(argv))

vexor/config.py

@@ -0,0 +1,62 @@
+"""Global configuration management for Vexor."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict
+
+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"
+
+
+@dataclass
+class Config:
+    api_key: str | None = None
+    model: str = DEFAULT_MODEL
+    batch_size: int = DEFAULT_BATCH_SIZE
+
+
+def load_config() -> Config:
+    if not CONFIG_FILE.exists():
+        return Config()
+    raw = json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+    return 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)),
+    )
+
+
+def save_config(config: Config) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    data: Dict[str, Any] = {}
+    if config.api_key:
+        data["api_key"] = config.api_key
+    if config.model:
+        data["model"] = config.model
+    data["batch_size"] = config.batch_size
+    CONFIG_FILE.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def set_api_key(value: str | None) -> None:
+    config = load_config()
+    config.api_key = value
+    save_config(config)
+
+
+def set_model(value: str) -> None:
+    config = load_config()
+    config.model = value
+    save_config(config)
+
+
+def set_batch_size(value: int) -> None:
+    config = load_config()
+    config.batch_size = value
+    save_config(config)

vexor/search.py

@@ -0,0 +1,152 @@
+"""Semantic search helpers backed by the Google Gemini embedding API."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator, 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 .text import Messages
+
+
+@dataclass(slots=True)
+class SearchResult:
+    """Container describing a single semantic search hit."""
+
+    path: Path
+    score: float
+
+
+class EmbeddingBackend(Protocol):
+    """Minimal protocol for components that can embed text batches."""
+
+    def embed(self, texts: Sequence[str]) -> np.ndarray:
+        """Return embeddings for *texts* as a 2D numpy array."""
+        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."""
+
+    def __init__(
+        self,
+        model_name: str = DEFAULT_MODEL,
+        *,
+        backend: EmbeddingBackend | None = None,
+        batch_size: int = 0,
+    ) -> 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"
+
+    @property
+    def device(self) -> str:
+        """Return a description of the remote backend in use."""
+        return self._device
+
+    def _encode(self, texts: Sequence[str]) -> np.ndarray:
+        embeddings = self._backend.embed(texts)
+        if embeddings.size == 0:
+            return embeddings
+        norms = np.linalg.norm(embeddings, axis=1, keepdims=True)
+        norms[norms == 0] = 1.0
+        return embeddings / norms
+
+    def embed_texts(self, texts: Sequence[str]) -> np.ndarray:
+        """Public helper to encode arbitrary text batches."""
+        return self._encode(texts)
+
+    def search(self, query: str, files: Sequence[Path], top_k: int = 5) -> List[SearchResult]:
+        """Return the *top_k* most similar files for *query*."""
+        clean_query = query.strip()
+        if not clean_query:
+            raise ValueError("Query text must not be empty")
+        if not files:
+            return []
+        file_labels = [self._prepare_text(path) for path in files]
+        file_vectors = self._encode(file_labels)
+        query_vector = self._encode([clean_query])[0]
+        similarities = cosine_similarity(
+            query_vector.reshape(1, -1), file_vectors
+        )[0]
+        scored = [
+            SearchResult(path=path, score=float(score))
+            for path, score in zip(files, similarities)
+        ]
+        scored.sort(key=lambda item: item.score, reverse=True)
+        return scored[:top_k]
+
+    @staticmethod
+    def _prepare_text(path: Path) -> str:
+        """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}"

vexor/text.py

@@ -0,0 +1,82 @@
+"""Centralized user-facing text for Vexor CLI."""
+
+from __future__ import annotations
+
+class Styles:
+    ERROR = "red"
+    WARNING = "yellow"
+    SUCCESS = "green"
+    INFO = "dim"
+    TITLE = "bold cyan"
+    TABLE_HEADER = "bold magenta"
+
+
+class Messages:
+    APP_HELP = "Vexor – A vector-powered CLI for semantic search over filenames."
+    HELP_QUERY = "Text used to semantically match file names."
+    HELP_SEARCH_PATH = "Root directory whose cached index will be used."
+    HELP_SEARCH_TOP = "Number of results to display."
+    HELP_INCLUDE_HIDDEN = "Use the index built with hidden files included."
+    HELP_INDEX_PATH = "Root directory to scan recursively for indexing."
+    HELP_INDEX_INCLUDE = "Include hidden files and directories when building the index."
+    HELP_INDEX_CLEAR = "Remove the cached index for the specified path (respecting include-hidden)."
+    HELP_DOCTOR = "Check whether the `vexor` command is available on the current PATH."
+    HELP_UPDATE = "Check if a newer Vexor release is available online."
+    HELP_SET_API_KEY = "Persist an API key in ~/.vexor/config.json."
+    HELP_CLEAR_API_KEY = "Remove the stored API key."
+    HELP_SET_MODEL = "Set the default embedding model."
+    HELP_SET_BATCH = "Set the default batch size (0 = single request)."
+    HELP_SHOW_CONFIG = "Show current configuration."
+
+    ERROR_API_KEY_MISSING = (
+        "Gemini API key is missing or still set to the placeholder. "
+        "Configure it via `vexor config --set-api-key <token>` or an environment variable."
+    )
+    ERROR_API_KEY_INVALID = (
+        "Gemini API key is invalid. Verify the stored token and try again."
+    )
+    ERROR_GENAI_PREFIX = "Gemini API request failed: "
+    ERROR_NO_EMBEDDINGS = "Gemini API returned no embeddings."
+    ERROR_EMPTY_QUERY = "Query text must not be empty."
+    ERROR_BATCH_NEGATIVE = "Batch size must be >= 0"
+
+    INFO_NO_FILES = "No files found in the selected directory."
+    INFO_NO_RESULTS = "No matching files found."
+    ERROR_INDEX_MISSING = (
+        "No cached index found for {path}. Run `vexor index --path \"{path}\"` first."
+    )
+    INFO_INDEX_SAVED = "Index saved to {path}."
+    INFO_INDEX_EMPTY = "Index contains no files."
+    INFO_INDEX_UP_TO_DATE = "Index already matches the current directory; nothing to do."
+    WARNING_INDEX_STALE = "Cached index for {path} appears outdated; run `vexor index --path \"{path}\"` to refresh."
+    INFO_INDEX_RUNNING = "Indexing files under {path}..."
+    INFO_INDEX_CLEARED = "Removed {count} cached index entr{plural} for {path}."
+    INFO_INDEX_CLEAR_NONE = "No cached index found for {path}."
+    INFO_API_SAVED = "API key saved."
+    INFO_API_CLEARED = "API key cleared."
+    INFO_MODEL_SET = "Default model set to {value}."
+    INFO_BATCH_SET = "Default batch size set to {value}."
+    INFO_CONFIG_SUMMARY = (
+        "API key set: {api}\n"
+        "Default model: {model}\n"
+        "Default batch size: {batch}"
+    )
+    INFO_SEARCH_RUNNING = "Searching cached 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` command is not on PATH. Install with pip or add the script directory to PATH."
+    )
+    INFO_UPDATE_CHECKING = "Checking latest Vexor version..."
+    INFO_UPDATE_CURRENT = "You are running Vexor v{current}."
+    INFO_UPDATE_AVAILABLE = (
+        "New version available: v{latest}. Visit {github} or {pypi} to download the update."
+    )
+    INFO_UPDATE_UP_TO_DATE = "You already have the latest version (v{latest})."
+    ERROR_UPDATE_FETCH = "Unable to fetch latest version information ({reason})."
+
+    TABLE_TITLE = "Vexor semantic file search results"
+    TABLE_HEADER_INDEX = "#"
+    TABLE_HEADER_SIMILARITY = "Similarity"
+    TABLE_HEADER_PATH = "File path"
+    TABLE_BACKEND_PREFIX = "Backend: "

vexor/utils.py

@@ -0,0 +1,50 @@
+"""Utility helpers for filesystem access and path handling."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable, List
+import os
+
+
+def resolve_directory(path: Path | str) -> Path:
+    """Resolve and validate a user supplied directory path."""
+    dir_path = Path(path).expanduser().resolve()
+    if not dir_path.exists():
+        raise FileNotFoundError(f"Directory does not exist: {dir_path}")
+    if not dir_path.is_dir():
+        raise NotADirectoryError(f"Path is not a directory: {dir_path}")
+    return dir_path
+
+
+def collect_files(root: Path | str, include_hidden: bool = False) -> List[Path]:
+    """Recursively collect files under *root*, optionally keeping hidden entries."""
+    directory = resolve_directory(root)
+    files: List[Path] = []
+    for dirpath, dirnames, filenames in os.walk(directory):
+        if not include_hidden:
+            dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+            filenames = [f for f in filenames if not f.startswith(".")]
+        current_dir = Path(dirpath)
+        for filename in filenames:
+            files.append(current_dir / filename)
+    files.sort()
+    return files
+
+
+def format_path(path: Path, base: Path | None = None) -> str:
+    """Return a user friendly representation of *path* relative to *base* when possible."""
+    if base:
+        try:
+            relative = path.relative_to(base)
+            return f"./{relative.as_posix()}"
+        except ValueError:
+            return str(path)
+    return str(path)
+
+
+def ensure_positive(value: int, name: str) -> int:
+    """Validate that *value* is positive."""
+    if value <= 0:
+        raise ValueError(f"{name} must be greater than 0")
+    return value

vexor-0.2.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: vexor
+Version: 0.2.0
+Summary: A vector-powered CLI for semantic search over filenames.
+Project-URL: Repository, https://github.com/scarletkc/vexor
+Author: scarletkc
+License: MIT
+License-File: LICENSE
+Keywords: ai,cli,semantic-search,typer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: google-genai>=0.5.0
+Requires-Dist: numpy>=1.23.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.1; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: twine>=5.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/scarletkc/vexor/refs/heads/main/assets/vexor.svg" alt="Vexor" width="50%" height="auto">
+
+# Vexor
+
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/vexor.svg)](https://pypi.org/project/vexor/)
+[![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)
+
+</div>
+
+---
+
+Vexor is a vector-powered CLI that searches file names semantically. It uses Google GenAI's `gemini-embedding-001` model to embed file names and queries, then ranks matches with cosine similarity.
+
+## Install
+Download from [releases](https://github.com/scarletkc/vexor/releases) without python, or with:
+```bash
+pip install vexor # or use pipx, uv
+```
+The CLI entry point is `vexor`.
+
+## Configure
+Set the Gemini API key once and reuse it everywhere:
+```bash
+vexor config --set-api-key "YOUR_KEY"
+```
+Optional defaults:
+```bash
+vexor config --set-model gemini-embedding-001
+vexor config --set-batch-size 0   # 0 = single request
+```
+Configuration is stored in `~/.vexor/config.json`.
+
+## Workflow
+1. **Index** the project root (includes every subdirectory):
+   ```bash
+   vexor index --path ~/projects/demo --include-hidden
+   ```
+2. **Search** from anywhere, pointing to the same path:
+   ```bash
+   vexor search "api client config" --path ~/projects/demo --top 5
+   ```
+   Output example:
+   ```
+   Vexor semantic file search results
+   ──────────────────────────────────
+   1   0.923   ./src/config_loader.py
+   2   0.871   ./src/utils/config_parse.py
+   3   0.809   ./tests/test_config_loader.py
+   ```
+
+Tips:
+- Keep one index per project root; subdirectories need separate indexes only if you explicitly run `vexor index` on them.
+- Hidden files are included only if both `index` and `search` use `--include-hidden`.
+
+## Commands
+| Command | Description |
+| ------- | ----------- |
+| `vexor index --path PATH [--include-hidden] [--clear]` | Recursively scans `PATH`, embeds file names, and writes a cache under `~/.vexor`. |
+| `vexor search QUERY --path PATH [--top K] [--include-hidden]` | Loads the cached embeddings for `PATH` and ranks matches for `QUERY`. |
+| `vexor doctor` | Checks whether the `vexor` command is available on the current `PATH`. |
+| `vexor update` | Fetches the latest release version and shows links to update via GitHub or PyPI. |
+| `vexor config --set-api-key/--clear-api-key` | Manage the stored Gemini API key. |
+| `vexor config --set-model/--set-batch-size/--show` | Manage default model and batch size. |

vexor-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+vexor/__init__.py,sha256=sxxZci6pouzNpymD1ejnMDepVWWu0RZ7rwM0RKkRg6I,234
+vexor/__main__.py,sha256=ZFzom1wCfP6TPXe3aoDFpNcUgjbCZ7Quy_vfzNsH5Fw,426
+vexor/cache.py,sha256=Y_NoKijKqYU8lq6vfx9W5DDB3kEkFP_mKPykJj0MhV4,9180
+vexor/cli.py,sha256=y_FKVkfAIJ506efaoPhhL_ffz4IAbYkOKSGbcK8zwu4,14175
+vexor/config.py,sha256=euhmbeXxxWn3uULBENFS0YYvNQuX53qjMwVGuejXwF0,1597
+vexor/search.py,sha256=tQG9MuAV3Us4eUl5Tez3sdUp6aolFQJfFREXN3qCnsc,5352
+vexor/text.py,sha256=ELD_0f4AXwQEJmiXvkC1sK6pPMQB3l-Xe_GBIkXd5eA,3890
+vexor/utils.py,sha256=kN8thdTBohRfCk-wO_BZtMpHdsQM6LN4tJBRxyrphpc,1727
+vexor-0.2.0.dist-info/METADATA,sha256=8X2YvrOnUdq6ymyMCeMVeegNgG6zVqCYN36cdwUniZw,4211
+vexor-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+vexor-0.2.0.dist-info/entry_points.txt,sha256=dvxp6Q1R1d6bozR7TwmpdJ0X_v83MkzsLPagGY_lfr0,40
+vexor-0.2.0.dist-info/licenses/LICENSE,sha256=wP7TAKRll1t9LoYGxWS9NikPM_0hCc00LmlLyvQBsL8,1066
+vexor-0.2.0.dist-info/RECORD,,

vexor-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vexor-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vexor = vexor.cli:run

vexor-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ScarletKc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.