vectr 1.0.0__py3-none-any.whl

agent/indexer/_types.py

@@ -0,0 +1,157 @@
+"""Chunk dataclass, EmbedProvider protocol, embed provider implementations."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from agent.config import (
+    EMBEDDING_DEFAULT_MODEL as _EMBEDDING_DEFAULT_MODEL,
+    EMBEDDING_MAX_SEQ_LENGTH as _EMBEDDING_MAX_SEQ_LENGTH,
+)
+
+
+# ---------------------------------------------------------------------------
+# Chunk dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class CodeChunk:
+    chunk_id: str
+    content: str
+    file_path: str
+    language: str
+    node_type: str
+    start_line: int
+    end_line: int
+    symbol_name: str
+
+
+# ---------------------------------------------------------------------------
+# Embedding provider protocol
+# ---------------------------------------------------------------------------
+
+class EmbedProvider(Protocol):
+    def embed(self, texts: list[str]) -> list[list[float]]: ...
+
+    def embed_query(self, texts: list[str]) -> list[list[float]]:
+        """Embed search-query text. Distinct from `embed()` (document/indexing side)
+        because some asymmetric embedding models require a different, model-
+        registered prompt for queries than for the passages they're matched
+        against. Providers with no such distinction may just delegate to
+        `embed()`.
+        """
+        ...
+
+
+class LocalEmbedProvider:
+    """Uses sentence-transformers (no API key). Default model: config.yaml embedding.default_model
+    (UPG-EMBEDDER-SWAP-GRANITE)."""
+
+    def __init__(self, model_name: str = _EMBEDDING_DEFAULT_MODEL) -> None:
+        from agent.model_cache import load_with_offline_preference, suppress_model_load_noise
+        suppress_model_load_noise()
+        import torch
+        from sentence_transformers import SentenceTransformer
+        cache_dir = Path.home() / ".cache" / "vectr" / "models"
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        # UPG-RERANKER-HF-NETWORK: prefer an offline (local_files_only) load
+        # when this model is already fully cached, so a warm daemon start
+        # never makes live huggingface.co calls (HEAD/GET on config.json,
+        # tokenizer_config.json, repo tree listings, ...) just to re-confirm
+        # a cache it already has. Falls back to a network-enabled load on a
+        # genuine cache miss (first run) so that UX is unchanged.
+        self._model = load_with_offline_preference(
+            # torch_dtype float32 is load-bearing on CPU (UPG-EMBED-CPU-DTYPE):
+            # transformers honors the checkpoint's declared dtype, and a model
+            # shipping bfloat16 weights (the current default does) runs through
+            # software-emulated bf16 matmuls on CPU — measured 12x slower than
+            # float32 for identical inputs. On CPU float32 is strictly correct;
+            # revisit only if a GPU/MPS device path is ever added.
+            lambda local_only: SentenceTransformer(
+                model_name,
+                cache_folder=str(cache_dir),
+                trust_remote_code=True,
+                device="cpu",
+                local_files_only=local_only,
+                model_kwargs={"torch_dtype": torch.float32},
+            ),
+            model_name,
+            str(cache_dir),
+        )
+        # Cap the encoder's sequence length (config.yaml embedding.max_seq_length).
+        # A long-context model's own config otherwise wins — the current default
+        # declares 8192, and encoding long chunks at full length on CPU has
+        # quadratic-attention cost that stalls a full-corpus index for hours.
+        # Only ever lowers: a model that already declares less keeps its own cap.
+        current_cap = getattr(self._model, "max_seq_length", None)
+        if current_cap is None or current_cap > _EMBEDDING_MAX_SEQ_LENGTH:
+            self._model.max_seq_length = _EMBEDDING_MAX_SEQ_LENGTH
+        # Asymmetric embedding models (arctic-embed and others) register a "query"
+        # prompt in their sentence-transformers config that must be prepended to
+        # search queries but NOT to the documents/chunks being indexed. Detected from
+        # the loaded model itself (never hardcoded) so symmetric models — which
+        # register no such prompt — embed queries and documents identically, unchanged.
+        self._has_query_prompt = "query" in getattr(self._model, "prompts", {})
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        embeddings = self._model.encode(
+            texts,
+            convert_to_numpy=True,
+            normalize_embeddings=True,
+            show_progress_bar=False,
+        )
+        return embeddings.tolist()
+
+    def embed_query(self, texts: list[str]) -> list[list[float]]:
+        if not self._has_query_prompt:
+            return self.embed(texts)
+        embeddings = self._model.encode(
+            texts,
+            prompt_name="query",
+            convert_to_numpy=True,
+            normalize_embeddings=True,
+            show_progress_bar=False,
+        )
+        return embeddings.tolist()
+
+
+class VoyageEmbedProvider:
+    """Uses Voyage AI code embedding model (requires VOYAGE_API_KEY)."""
+
+    def __init__(self, model_name: str = "voyage-code-2") -> None:
+        import voyageai  # type: ignore
+        self._client = voyageai.Client()
+        self._model = model_name
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        result = self._client.embed(texts, model=self._model)
+        return result.embeddings
+
+    def embed_query(self, texts: list[str]) -> list[list[float]]:
+        return self.embed(texts)
+
+
+class OpenAIEmbedProvider:
+    """Uses OpenAI embedding model (requires OPENAI_API_KEY)."""
+
+    def __init__(self, model_name: str = "text-embedding-3-small") -> None:
+        from openai import OpenAI
+        self._client = OpenAI()
+        self._model = model_name
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        response = self._client.embeddings.create(input=texts, model=self._model)
+        return [item.embedding for item in response.data]
+
+    def embed_query(self, texts: list[str]) -> list[list[float]]:
+        return self.embed(texts)
+
+
+def get_embed_provider(model_spec: str) -> EmbedProvider:
+    """Factory: parse VECTR_EMBED_MODEL and return the right provider."""
+    if model_spec.startswith("voyage"):
+        return VoyageEmbedProvider(model_spec)
+    if model_spec.startswith("openai/"):
+        return OpenAIEmbedProvider(model_spec.split("/", 1)[1])
+    return LocalEmbedProvider(model_spec)

agent/instance_registry.py

@@ -0,0 +1,127 @@
+"""~/.vectr/instances.json — per-workspace daemon registry.
+
+Tracks all running vectr daemons so multiple IDE windows can each
+get their own vectr instance on its own port.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import socket
+import time
+from pathlib import Path
+from typing import Any
+
+REGISTRY_PATH = Path.home() / ".vectr" / "instances.json"
+
+
+def workspace_hash(path: str) -> str:
+    """sha256(absolute_workspace_path)[:12] — same prefix used for cache dirs."""
+    return hashlib.sha256(path.encode()).hexdigest()[:12]
+
+
+def _is_pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # process exists, we lack permission to signal it
+
+
+def _port_is_free(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.bind(("127.0.0.1", port))
+            return True
+        except OSError:
+            return False
+
+
+class InstanceRegistry:
+    def __init__(self, registry_path: Path = REGISTRY_PATH) -> None:
+        self._path = registry_path
+
+    def _read(self) -> dict[str, Any]:
+        if not self._path.exists():
+            return {}
+        try:
+            return json.loads(self._path.read_text())
+        except (json.JSONDecodeError, OSError):
+            return {}
+
+    def _write(self, data: dict[str, Any]) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self._path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(data, indent=2))
+        os.rename(tmp, self._path)
+
+    def prune_dead(self) -> None:
+        """Remove entries whose PIDs are no longer alive."""
+        data = self._read()
+        live = {k: v for k, v in data.items() if _is_pid_alive(v["pid"])}
+        if len(live) != len(data):
+            self._write(live)
+
+    def get(self, ws_hash: str) -> dict[str, Any] | None:
+        return self._read().get(ws_hash)
+
+    def list_all(self) -> dict[str, Any]:
+        return self._read()
+
+    def register(
+        self,
+        ws_hash: str,
+        workspace: str,
+        port: int,
+        pid: int,
+        extra_roots: list[str] | None = None,
+        code_workspace_file: str | None = None,
+    ) -> None:
+        data = self._read()
+        data[ws_hash] = {
+            "workspace": workspace,
+            "port": port,
+            "pid": pid,
+            "started_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            # Extra roots + the originating .code-workspace file (if any) are
+            # recorded here so `vectr status` can show what this instance
+            # actually serves without re-deriving it from CLI args it never
+            # saw (UPG-CLI-STATUS-MODE).
+            "extra_roots": extra_roots or [],
+            "code_workspace_file": code_workspace_file,
+        }
+        self._write(data)
+
+    def unregister(self, ws_hash: str) -> None:
+        data = self._read()
+        data.pop(ws_hash, None)
+        self._write(data)
+
+    def find_free_port(self, ws_hash: str, preferred_port: int) -> int:
+        """Allocate a port per spec algorithm:
+
+        1. If ws_hash has a live entry → return its port (caller detects no-op).
+        2. If ws_hash has a dead entry → try to reuse its previous port first
+           (avoids rewriting .mcp.json).
+        3. Scan from preferred_port upward until a free port binds (up to 100 tries).
+        """
+        entry = self._read().get(ws_hash)
+
+        if entry is not None:
+            pid, port = entry["pid"], entry["port"]
+            if _is_pid_alive(pid):
+                return port  # caller should treat as no-op
+            if _port_is_free(port):
+                return port
+
+        for offset in range(100):
+            candidate = preferred_port + offset
+            if _port_is_free(candidate):
+                return candidate
+
+        raise RuntimeError(
+            f"No free port found in range {preferred_port}–{preferred_port + 99}"
+        )

agent/llm_client.py

@@ -0,0 +1,8 @@
+"""Reports the configured LLM model name for API response metadata."""
+from __future__ import annotations
+
+import os
+
+
+def get_model() -> str:
+    return os.getenv("LLM_MODEL", "claude-sonnet-4-6")

agent/model_cache.py

@@ -0,0 +1,101 @@
+"""Shared local-model-cache helpers for embedder/reranker loading.
+
+Both the embedder (agent/indexer/_types.py:LocalEmbedProvider) and the
+reranker (agent/searcher.py:_Reranker) load a Hugging Face model that, in
+the common case, is already fully present in vectr's local model cache
+(``~/.cache/vectr/models``). Without an explicit offline hint,
+``sentence_transformers`` still performs live network calls against
+huggingface.co (HEAD/GET on config.json, tokenizer_config.json, repo tree
+listings, ...) to check for a newer revision before falling back to the
+cache — costing seconds of network-dependent latency on every daemon
+start and failing hard on an air-gapped or proxied machine despite a
+complete local cache (UPG-RERANKER-HF-NETWORK).
+
+``load_with_offline_preference`` is the one entry point both load sites
+use: it checks whether the model is already cached via
+``huggingface_hub``'s own cache-lookup API (never re-deriving the HF
+``models--org--name`` on-disk layout by hand), prefers an offline
+(``local_files_only=True``) load when it is, and always falls back to a
+normal network-enabled load — either on a genuine cache miss (first run)
+or if the offline load raises anyway (an incomplete/corrupted cache
+entry) — so first-run UX is never broken by this change.
+"""
+from __future__ import annotations
+
+from typing import Callable, TypeVar
+
+T = TypeVar("T")
+
+
+def suppress_model_load_noise() -> None:
+    """Silence tqdm download/fetch progress bars and INFO-level logging that
+    sentence-transformers' underlying huggingface_hub/transformers
+    dependencies print on model load (UPG-CLI-SMALL-UX): implementation
+    noise to a CLI user watching `vectr watch` index a workspace in the
+    foreground, and clutter in the daemon's own log file for `start`/
+    `restart` (whose stdout/stderr are redirected there, not the terminal,
+    but a user tailing the log while `vectr status` reports "still
+    loading" hits the same noise).
+
+    Uses each library's own official suppression API rather than setting
+    environment variables, since some versions of these libraries only read
+    the env var once at import time — calling the API instead works
+    regardless of import order or of which module happens to import
+    sentence_transformers first. Best-effort: never raises, so an older or
+    newer dependency version missing one of these functions never breaks
+    model loading.
+    """
+    try:
+        from huggingface_hub.utils import disable_progress_bars
+        disable_progress_bars()
+    except Exception:
+        pass
+    try:
+        from transformers.utils import logging as _hf_logging
+        _hf_logging.set_verbosity_error()
+    except Exception:
+        pass
+
+
+def is_model_cached(model_name: str, cache_dir: str) -> bool:
+    """Best-effort check for whether ``model_name`` already has a snapshot in
+    ``cache_dir`` (vectr's Hugging Face cache root).
+
+    Probes for ``config.json`` via ``huggingface_hub.try_to_load_from_cache`` —
+    every HF model repo vectr loads (sentence-transformers embedders and
+    cross-encoder rerankers alike) ships one. This is a proxy for "this
+    repo's snapshot already exists locally", not a guarantee every auxiliary
+    file is present; ``load_with_offline_preference`` below still falls back
+    to a network-enabled load if the offline attempt raises anyway.
+    """
+    try:
+        from huggingface_hub import try_to_load_from_cache
+    except Exception:
+        return False
+    try:
+        hit = try_to_load_from_cache(model_name, "config.json", cache_dir=cache_dir)
+    except Exception:
+        return False
+    return isinstance(hit, str)
+
+
+def load_with_offline_preference(
+    build_fn: Callable[[bool], T], model_name: str, cache_dir: str
+) -> T:
+    """Instantiate a Hugging-Face-backed model, preferring an offline load
+    (no network calls at all) when ``model_name`` is already present in
+    ``cache_dir``, and falling back to a normal network-enabled load either
+    on a genuine cache miss or if the offline load raises anyway.
+
+    ``build_fn(local_files_only)`` must construct and return the model,
+    passing ``local_files_only`` straight through to the underlying
+    ``from_pretrained`` call (e.g. via ``SentenceTransformer(...,
+    local_files_only=local_files_only)`` /
+    ``CrossEncoder(..., local_files_only=local_files_only)``).
+    """
+    if is_model_cached(model_name, cache_dir):
+        try:
+            return build_fn(True)
+        except Exception:
+            pass  # incomplete/corrupted cache entry — fall through to network
+    return build_fn(False)

agent/prompt_templates.py

@@ -0,0 +1,31 @@
+"""Loader for vectr's bundled prompt/config templates (UPG-PROMPTS-AS-DATA).
+
+`main.py`'s IDE-integration writers (CLAUDE.md, session-start guidance,
+`.mcp.json` variants, the Cursor rules frontmatter, the hook
+no-double-recall line) used to embed these as module-level Python string
+constants. They are plain text/markdown/JSON content with `.format()`
+placeholders, not code, so they live in `agent/templates/` and are loaded
+here instead — keeping prompt copy editable without touching Python and
+letting non-engineers review/tune it as data.
+
+Resolved via ``importlib.resources`` (not a ``cwd``-relative ``open()``) so
+this works identically whether vectr runs from the repository checkout or
+as an installed wheel (global binary), and results are cached since these
+files are read repeatedly (every `vectr init` / IDE-config write) but never
+change within a process lifetime.
+"""
+from __future__ import annotations
+
+import importlib.resources as _ilr
+from functools import cache
+
+
+@cache
+def load_template(name: str) -> str:
+    """Read and return the exact text content of `agent/templates/<name>`.
+
+    Caching is safe because these are static, packaged files — not
+    per-workspace or per-request state.
+    """
+    resource = _ilr.files("agent").joinpath("templates").joinpath(name)
+    return resource.read_text(encoding="utf-8")