patchvec 0.5.8__py3-none-any.whl → 0.5.9__py3-none-any.whl

{patchvec-0.5.8.dist-info → patchvec-0.5.9.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: patchvec
-Version: 0.5.8
-Summary: Patchvec — A lightweight, pluggable vector search microservice.
+Version: 0.5.9
+Summary: PaveDB — A lightweight, pluggable vector search microservice.
 Author: Rodrigo Rodrigues da Silva
 Author-email: rodrigo@flowlexi.com
 License: AGPL-3.0-or-later
@@ -24,7 +24,6 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn[standard]>=0.30.6
-Requires-Dist: txtai>=6.3.0
 Requires-Dist: pydantic>=2.8.2
 Requires-Dist: python-multipart>=0.0.9
 Requires-Dist: pypdf>=5.0.0
@@ -32,14 +31,14 @@ Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: python-dotenv>=1.0.1
 Requires-Dist: faiss-cpu>=1.7.1
 Requires-Dist: torch>=2.10.0
+Requires-Dist: sentence-transformers>=2.7.0
 Provides-Extra: cpu
-Provides-Extra: sbert
-Requires-Dist: sentence-transformers>=2.7.0; extra == "sbert"
 Provides-Extra: openai
 Requires-Dist: openai>=1.0.0; extra == "openai"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: httpx; extra == "test"
+Requires-Dist: datasets>=3.5.0; extra == "test"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -67,7 +66,7 @@ Upload → chunk → index (with metadata) → search via REST and CLI.
 - Metadata filters on search (`{"filters": {"docid": "DOC-1"}}`)
 - REST and CLI entry points
 - Health/metrics endpoints + Prometheus exporter
-- Pluggable embeddings and stores; default backend is local
+- Pluggable embeddings and stores; default stack is local FAISS + SBERT
 
 ## Requirements
 - Python 3.10–3.14
@@ -102,27 +101,30 @@ export PATCHVEC_AUTH__GLOBAL_KEY="your-secret"
 ```
 
 ## Minimal config (optional)
-By default PatchVec runs with sensible local defaults. To customize, create
-`config.yml`:
+By default PatchVec runs with sensible local defaults. For a user install,
+customize `~/patchvec/config.yml`:
 ```yaml
 vector_store:
-  type: default
+  type: faiss
 embedder:
-  type: default
+  type: sbert
 auth:
   mode: static
   global_key: ${PATCHVEC_GLOBAL_KEY}
 ```
 Then export:
 ```bash
-export PATCHVEC_CONFIG=./config.yml
 export PATCHVEC_GLOBAL_KEY="your-secret"
 ```
+If you keep the file elsewhere, point the runtime at it explicitly:
+```bash
+export PATCHVEC_CONFIG=/path/to/config.yml
+```
 
 ## CLI example
 ```bash
 pavecli create-collection demo books
-pavecli upload demo books demo/20k_leagues.txt --docid=verne-20k \
+pavecli ingest demo books demo/20k_leagues.txt --docid=verne-20k \
   --metadata='{"lang":"en"}'
 pavecli search demo books "captain nemo" -k 5
 ```

patchvec-0.5.9.dist-info/RECORD

@@ -0,0 +1,43 @@
+patchvec-0.5.9.dist-info/licenses/LICENSE,sha256=2KbMMavBa2dIx6IfIWEfWh7DP2fSLKI9faHBm5VJa-4,34020
+pave/__init__.py,sha256=g9xY4EojFJqm-dH3UjXIFtzi_T5_3tUFNY3ipocWCA0,227
+pave/auth.py,sha256=j1q-6RGSlOvQDCkM_uJIzllz7H0vVIgS8e5KXtMTDWA,5242
+pave/cli.py,sha256=6HaN7HEiTd4ALroMPEYwF58u74EDo-hyRvSPxdeDETY,11027
+pave/config.py,sha256=4fil_ovxlcZbQSLz-IbdFz_vUtWGdhAqgzOdo-NbW0c,11663
+pave/filters.py,sha256=QDThvoUJXLGnoge4Gie2YCboanT4wmC-CGECbbBPd_8,5163
+pave/log.py,sha256=L8pPCP32Mbxt9oLoKSY4NIfptqYG6R-cW3V0NddozTY,8203
+pave/main.py,sha256=aDsLKeSEvMqHKd_d1sCegJ8_LyVQy1MnpK0qhISx7c8,11926
+pave/metadb.py,sha256=jy2hMxEv0Rw759eoG3S08AnZE0BfXgVg4JJB7ilZlDk,21709
+pave/metrics.py,sha256=COqwrYtOepPudMQWimaV1Vm47rcTTFA2NxvY0Vb3sus,6457
+pave/preprocess.py,sha256=Wu7VEhcUdXX8KggPbPTWiKmcOCEpPmlhuS8SbBK5Ztw,5444
+pave/runtime_paths.py,sha256=v8XydI1uh1P-v_C5dWi-2Rt_7WnMObreXexxgMI1UxE,2349
+pave/schemas.py,sha256=ZrtslEt87u9ck_X24YDGuH73fCGQLu9fkYqefLEyVC4,1152
+pave/service.py,sha256=ZZ2hVvOuEb258fi7dMc2dtLdU5RXBN7uEB6PFpo6HdE,12021
+pave/ui.py,sha256=x5IrGyz78PXpCMSj_Y8vX4mx3b3yAErE60AXBCPgz7E,6343
+pave/assets/__init__.py,sha256=Cxqbj0YBvSMcD8_OvKII2OhB_5ZiJujcyh7OZucbFdo,113
+pave/assets/config.yml.example,sha256=xQjInMykLN8b2yRhc2FrlkRknNsa4I1zNFZSGtd_BeI,8843
+pave/assets/patchvec_icon_192.png,sha256=kUkXir9MtwxWTd_9hPTdycDwdRCimjprJhmaIP6R-XM,9733
+pave/assets/tenants.yml.example,sha256=dshjFtnMiaeBATWZD8bHCuzpbMSS4N6vcUuUD6QjaZo,644
+pave/assets/ui.html,sha256=E8mrkuDEQi2-6vyG6AAkXLxfOb7VIqYe22_uLoPLKGo,5070
+pave/backends/__init__.py,sha256=WkrPPDdSCgXUR-0CeVdjwmflulae1bayYLPWuuqydVc,322
+pave/backends/base.py,sha256=BxGwzv7FPQjonFyzG_Gnb8zUGUUdQ0OJMU9GTqBtrJc,639
+pave/backends/faiss.py,sha256=YvajvqpVcRcZMmIeXnq7WAL_f6W8GaqnH_eDAtXU4u8,4666
+pave/backends/qdrant.py,sha256=EzHN66C7ycLoUxEhm4RhoP6ZTVVqHwhW3oj8QSAVRRI,1218
+pave/embedders/__init__.py,sha256=LaATyOd6M4nr6YGhppj_E1uQ-OxH9ZsgHBIB2uJMaFQ,208
+pave/embedders/base.py,sha256=c5gE7G2Pa7Zu5kS8sKhXNu8ynddhHYn-lMPB5yDWKWo,505
+pave/embedders/factory.py,sha256=xurK3L5Y4Z5x0W20rRZxXmj7lex0EDZ2fmRPysjZYIc,619
+pave/embedders/openai.py,sha256=8CwgRglQEbIuc3-TdbC_yTjqd5oMFHoboBfKW_ATLdU,1498
+pave/embedders/sbert.py,sha256=HsZwFfXtwYSOTtTf1m7SgqKKGvEDc852BL6PuAKBB_M,2039
+pave/routes/__init__.py,sha256=rpFdUG6Sk7fhy51kxewmo0WHle_UUphis4rWo6kdcks,539
+pave/routes/admin.py,sha256=4s_ocNYy929kEFLbsipdzLkAnPhNSPY8wHAldj7qpSs,3926
+pave/routes/collections.py,sha256=W4ZkLegKRlrvGDgXcBB15fZBMJLApAz09wyfQNv_90o,3883
+pave/routes/documents.py,sha256=NxyXlS4ZJ3RXaji9kFtkHlUzNDJE4BWpck8eU7qzfpo,5438
+pave/routes/health.py,sha256=PWmhIp8klS2P9l8e6ShkZOgEk04npWPDPSD5J1P8koY,3524
+pave/routes/search.py,sha256=JX-Esnl93xKnRuN5cP-ajN9LmXnL8JUMysbp6PsC2kM,5295
+pave/stores/__init__.py,sha256=fpaYUUTfVr_h6Fn28iugATtjoeuXH78nQ_s4OLyqTcE,169
+pave/stores/base.py,sha256=7IrmV9nqoI_3kad2ZkFa8LI8i8_f5oZ24bSOPddXqoA,3064
+pave/stores/local.py,sha256=vlDa2gjiSPWelHHj9sVN7gt6JA_g2N6jQZAoDRO4Yxw,28729
+patchvec-0.5.9.dist-info/METADATA,sha256=xXE2HKA125nkhpY3CQFwyCYQSKpyyyVKTzEogd5sZVw,4798
+patchvec-0.5.9.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+patchvec-0.5.9.dist-info/entry_points.txt,sha256=L6cnN4Byk5eDON2d4ipquuLowUjo7-5wpxLb-kThytQ,75
+patchvec-0.5.9.dist-info/top_level.txt,sha256=AbaAN6M4jryKL79DrYPnt49TpE2sjp97qYmm31RD_-U,5
+patchvec-0.5.9.dist-info/RECORD,,

{patchvec-0.5.8.dist-info → patchvec-0.5.9.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.0)
+Generator: setuptools (82.0.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pave/assets/config.yml.example

@@ -0,0 +1,224 @@
+# PatchVec sample configuration
+# Copy to config.yml and adjust.
+# Secrets (API keys) should live in a separate untracked file — see tenants.yml.example.
+#
+# Default user-install paths:
+#   config:  ~/pavedb/config.yml
+#   tenants: ~/pavedb/tenants.yml
+#   data:    ~/pavedb/data
+#
+# Distro-like install example:
+#   config:  /etc/pavedb/config.yml
+#   tenants: /var/pavedb/tenants.yml
+#   data:    /var/pavedb/data
+#
+# Config file location override:
+#   PAVEDB_CONFIG=/etc/pavedb/config.yml
+#
+# In Docker/systemd deployments always set PAVEDB_CONFIG explicitly — the
+# default path expands ~ relative to the process user, which may not be what
+# you expect inside a container. Example compose snippet:
+#
+#   environment:
+#     PAVEDB_CONFIG: /etc/pavedb/config.yml
+#   volumes:
+#     - ./config.yml:/etc/pavedb/config.yml:ro
+#
+# All keys can also be overridden inline via environment variables:
+#   PAVEDB_<KEY>=value          (top-level, e.g. PAVEDB_DATA_DIR)
+#   PAVEDB_<SECTION>__<KEY>=val (nested,    e.g. PAVEDB_LOG__LEVEL=debug)
+# Legacy PATCHVEC_* vars still work in v0.5.9 but will be removed in v0.6.
+#
+# `auth.tenants_file` is optional. If unset, its default is `None` and no
+# tenants sidecar file is loaded.
+# If set, PaveDB loads that sidecar first. Then inline tenant config is
+# applied with precedence:
+#   env vars > config.yml > tenants.yml > defaults
+# Example: define tenant "acme" entirely from env:
+#   PAVEDB_AUTH__API_KEYS__acme=change-me
+#   PAVEDB_TENANTS__acme__MAX_CONCURRENT=5
+
+# ---------------------------------------------------------------------------
+# Storage
+# ---------------------------------------------------------------------------
+
+# Data directory — ~ is expanded at startup.
+# Default (library/dev): ~/pavedb/data
+# For distro-like installs use an absolute path, e.g. /var/pavedb/data.
+data_dir: ~/pavedb/data
+
+# ---------------------------------------------------------------------------
+# Common collection
+# ---------------------------------------------------------------------------
+# When enabled, every tenant search also queries a shared "common" collection
+# and merges the results. Useful for org-wide reference data (e.g. a shared
+# code/term dictionary) that should be visible to all tenants.
+# The common collection is owned by common_tenant and is never rate-limited.
+
+common_enabled: false
+common_tenant: global        # tenant that owns the common collection
+common_collection: common    # collection name within that tenant
+
+# ---------------------------------------------------------------------------
+# Authentication
+# ---------------------------------------------------------------------------
+
+auth:
+  # none   — no auth; all requests accepted. Dev/private deployments only.
+  #          enforce_policy() will reject auth=none on non-loopback interfaces.
+  # static — Bearer token per tenant; keys defined below or in tenants_file.
+  mode: static
+
+  # Default tenant name when auth.mode=none (no key required).
+  default_access_tenant: public
+
+  # Global admin key — grants access to all tenants and admin routes.
+  # Always read from the environment; never hardcode in committed files.
+  global_key: ${PAVEDB_GLOBAL_KEY}
+
+  # External tenant→key mapping file.
+  # Keep the same key paths there (`auth.api_keys`, `tenants.*`).
+  # User install default:  ~/pavedb/tenants.yml
+  # Distro-like install:   /var/pavedb/tenants.yml
+  # tenants_file: ~/pavedb/tenants.yml
+
+  # Inline tenant→key mapping (fallback; keep empty in the repo).
+  api_keys: {}
+
+# ---------------------------------------------------------------------------
+# Vector store
+# ---------------------------------------------------------------------------
+
+vector_store:
+  # faiss   — local FAISS index (built-in, no extra services required).
+  type: faiss
+
+  # Options for type=faiss.
+  faiss:
+    embed_model: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
+    max_query_chars: 4000
+
+# ---------------------------------------------------------------------------
+# Embedder
+# ---------------------------------------------------------------------------
+# Controls how text is converted to vectors before indexing and querying.
+# The embedder is shared across all collections (per-collection config: v0.6).
+
+embedder:
+  # sbert  — direct sentence-transformers (recommended local default).
+  # openai — OpenAI embeddings API (requires API key, adds latency).
+  type: sbert
+
+  # Used by type=sbert.
+  sbert:
+    model: sentence-transformers/all-MiniLM-L6-v2
+    batch_size: 64
+    device: auto   # cpu | cuda | mps | auto
+
+  # Used by type=openai.
+  openai:
+    model: text-embedding-3-small
+    batch_size: 256
+    api_key: ${PAVEDB_OPENAI_API_KEY}
+    dim: 1536
+
+# ---------------------------------------------------------------------------
+# Ingest limits
+# ---------------------------------------------------------------------------
+
+ingest:
+  # Reject uploads larger than this (MB). 0 = unlimited.
+  # Also set your reverse proxy: e.g. nginx client_max_body_size >= this value.
+  max_file_size_mb: 500
+
+  # Max parallel ingests; excess requests get 503 immediately.
+  # Ingest is CPU/memory heavy — keep this well below your core count.
+  # 0 = unlimited (not recommended in production).
+  max_concurrent: 7
+
+# Reverse-proxy timeout guidance for ingest endpoints:
+# Ingest embeds the entire document before responding; large files can take
+# tens of seconds. Raise these nginx directives accordingly:
+#
+#   proxy_read_timeout   300;  # wait up to 5 min for upstream response
+#   client_body_timeout  120;  # wait up to 2 min for client to send body
+#
+# Your HTTP client read timeout should also be at least 300 s for ingest.
+
+# ---------------------------------------------------------------------------
+# Search limits
+# ---------------------------------------------------------------------------
+
+search:
+  # Max parallel searches; excess requests get 503 immediately.
+  # 0 = unlimited (not recommended in production).
+  max_concurrent: 42
+
+  # Per-search timeout in ms; returns 503 on expiry. 0 = no timeout.
+  timeout_ms: 30000
+
+# ---------------------------------------------------------------------------
+# Per-tenant concurrency limits
+# ---------------------------------------------------------------------------
+# Applies to all tenant-scoped routes (search, ingest, collection ops).
+# Admin requests and global-key requests bypass these limits.
+# Per-tenant overrides can be set in tenants.yml (see tenants.yml.example).
+# Moving-window limits (max_rpm, max_rph) require SQLite — post-v0.5.8.
+
+tenants:
+  default_max_concurrent: 10  # applies to every tenant; 0 = unlimited
+
+# ---------------------------------------------------------------------------
+# Text preprocessing
+# ---------------------------------------------------------------------------
+# Controls how plain-text (.txt) files are split into chunks before embedding.
+# Overlap ensures context is preserved across chunk boundaries.
+
+preprocess:
+  txt_chunk_size: 1000     # characters per chunk
+  txt_chunk_overlap: 200   # characters of overlap between adjacent chunks
+
+# ---------------------------------------------------------------------------
+# Server
+# ---------------------------------------------------------------------------
+# These defaults are overridden by env vars HOST / PORT / RELOAD / WORKERS.
+
+server:
+  host: 0.0.0.0
+  port: 8086
+  reload: false
+  workers: 1
+
+  # Keep-alive timeout in seconds (passed to uvicorn --timeout-keep-alive).
+  # Must be lower than your reverse proxy's keepalive_timeout.
+  # nginx default is 75 s — set this to 65 when behind nginx.
+  timeout_keep_alive: 75
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+
+log:
+  # Dev log level (stderr). DEBUG | INFO | WARNING | ERROR — default INFO.
+  # Overridden by PAVEDB_LOG__LEVEL env var (e.g. in Makefile: debug).
+  # Per-namespace overrides: log.debug / log.watch / log.quiet (list of loggers).
+  level: INFO
+
+  # Ops log — one structured JSON line per operation (search, ingest, delete…).
+  # Fields: ts, op, tenant, collection, latency_ms, status, error_code, hits.
+  # null (off) | stdout | /path/to/ops.jsonl
+  # stdout is recommended for Docker/12-factor; pave uses stderr for the dev log.
+  # File paths suit traditional deployments; no rotation is provided here.
+  ops_log: null
+
+  # Uvicorn access log destination.
+  # null (use uvicorn default) | stdout | /path/to/access.log
+  access_log: null
+
+# ---------------------------------------------------------------------------
+# Instance branding (optional)
+# ---------------------------------------------------------------------------
+
+instance:
+  name: PatchVec
+  desc: Vector Search Microservice (pluggable, functional)

pave/assets/tenants.yml.example

@@ -0,0 +1,19 @@
+# Untracked secrets file with tenant API keys and per-tenant limits.
+# Name it 'tenants.yml', adjust and DO NOT commit.
+# The installed default should be innocuous; uncomment the examples you need.
+#
+# auth:
+#   api_keys:
+#     acme: change-me
+#     umbrella: change-me
+
+# Per-tenant concurrency overrides.
+# Omit a tenant entry to fall back to tenants.default_max_concurrent in config.yml.
+# 0 = unlimited for that tenant.
+# Moving-window limits (max_rpm, max_rph) will be added here after SQLite lands.
+#
+# tenants:
+#   acme:
+#     max_concurrent: 5   # overrides global default for acme; 0 = unlimited
+#   umbrella:
+#     max_concurrent: 20

pave/auth.py

@@ -24,7 +24,7 @@ def _raise_401():
             "code": "auth_invalid",
             "error": "missing or invalid authorization header",
         },
-        headers={"WWW-Authenticate": 'Bearer realm="patchvec", error="invalid_token"'},
+        headers={"WWW-Authenticate": 'Bearer realm="pavedb", error="invalid_token"'},
     )
 
 def _raise_403():
@@ -33,7 +33,7 @@ def _raise_403():
         detail={"code": "auth_forbidden", "error": "forbidden"},
         headers={
             "WWW-Authenticate":
-                'Bearer realm="patchvec", error="insufficient_scope"'
+                'Bearer realm="pavedb", error="insufficient_scope"'
         },
     )
 
@@ -127,8 +127,8 @@ async def tenant_rate_limit(
 # --- Startup security policy -------------------------------------------------
 
 def _is_dev(cfg) -> bool:
-    # check dev flag (CFG or PATCHVEC_DEV)
-    return bool(cfg.get("dev", False)) or str(cfg.get("PATCHVEC_DEV", "0")) == "1"
+    # check dev flag from config/env overlay
+    return bool(cfg.get("dev", False))
 
 def enforce_policy(cfg) -> None:
     """
@@ -142,7 +142,7 @@ def enforce_policy(cfg) -> None:
         if not dev:
             raise RuntimeError(
                 "auth.mode=none not allowed in production. "
-                "Set auth.mode=static with a key or run with PATCHVEC_DEV=1 for dev."
+                "Set auth.mode=static with a key or run with PAVEDB_DEV=1 for dev."
             )
         host = str(cfg.get("server.host", "127.0.0.1")).strip()
         if host not in ("127.0.0.1", "localhost"):

pave/backends/__init__.py

@@ -0,0 +1,13 @@
+# (C) 2026 Rodrigo Rodrigues da Silva <rodrigo@flowlexi.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from .base import SearchHit, VectorBackend
+from .faiss import FaissBackend
+from .qdrant import QdrantVectorBackend
+
+__all__ = [
+    "FaissBackend",
+    "QdrantVectorBackend",
+    "SearchHit",
+    "VectorBackend",
+]

pave/backends/base.py

@@ -0,0 +1,29 @@
+# (C) 2026 Rodrigo Rodrigues da Silva <rodrigo@flowlexi.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+from typing import Protocol
+
+
+SearchHit = tuple[str, float]
+
+
+class VectorBackend(Protocol):
+    def initialize(self) -> None: ...
+
+    def add(self, rids: list[str], vectors: NDArray[np.float32]) -> None: ...
+
+    def search(
+        self,
+        vector: NDArray[np.float32],
+        k: int,
+    ) -> list[SearchHit]: ...
+
+    def delete(self, rids: list[str]) -> None: ...
+
+    def flush(self) -> None: ...
+
+    def close(self) -> None: ...

pave/backends/faiss.py

@@ -0,0 +1,153 @@
+# (C) 2026 Rodrigo Rodrigues da Silva <rodrigo@flowlexi.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import faiss
+import numpy as np
+from numpy.typing import NDArray
+
+from .base import SearchHit
+
+
+class FaissBackend:
+    def __init__(
+        self,
+        dimension: int,
+        *,
+        storage_dir: Path,
+    ) -> None:
+        self._dimension = int(dimension)
+        self._storage_dir = storage_dir
+        self._index = faiss.IndexIDMap2(faiss.IndexFlatIP(self._dimension))
+        self._rid_to_id: dict[str, int] = {}
+        self._id_to_rid: dict[int, str] = {}
+        self._next_id = 0
+
+    @property
+    def _index_file(self) -> Path:
+        return self._storage_dir / "faiss.index"
+
+    @property
+    def _map_file(self) -> Path:
+        return self._storage_dir / "id_map.json"
+
+    def initialize(self) -> None:
+        if not self._index_file.is_file() or not self._map_file.is_file():
+            return
+
+        loaded = faiss.read_index(str(self._index_file))
+        loaded_dim = int(getattr(loaded, "d", -1))
+        if loaded_dim != self._dimension:
+            raise ValueError(
+                "FAISS index dimension mismatch: "
+                f"expected {self._dimension}, found {loaded_dim}"
+            )
+        self._index = loaded
+        data = json.loads(self._map_file.read_text(encoding="utf-8"))
+        rid_to_id_raw = data.get("rid_to_id", {})
+        id_to_rid_raw = data.get("id_to_rid", {})
+        self._rid_to_id = {
+            str(rid): int(iid)
+            for rid, iid in rid_to_id_raw.items()
+        }
+        self._id_to_rid = {
+            int(iid): str(rid)
+            for iid, rid in id_to_rid_raw.items()
+        }
+        self._next_id = int(data.get("next_id", 0))
+
+    def add(self, rids: list[str], vectors: NDArray[np.float32]) -> None:
+        if not rids:
+            return
+        if len(rids) != int(vectors.shape[0]):
+            raise ValueError("rids and vectors length mismatch")
+
+        unique_rids: list[str] = []
+        rid_to_vector: dict[str, NDArray[np.float32]] = {}
+        for idx, rid in enumerate(rids):
+            srid = str(rid)
+            if srid not in rid_to_vector:
+                unique_rids.append(srid)
+            rid_to_vector[srid] = vectors[idx]
+
+        reindex_rids = [rid for rid in unique_rids if rid in self._rid_to_id]
+        if reindex_rids:
+            self.delete(reindex_rids)
+
+        matrix = np.vstack([rid_to_vector[rid] for rid in unique_rids]).astype(
+            np.float32,
+            copy=False,
+        )
+        normed = matrix.copy()
+        faiss.normalize_L2(normed)
+
+        int_ids: list[int] = []
+        for rid in unique_rids:
+            iid = self._next_id
+            self._next_id += 1
+            self._rid_to_id[rid] = iid
+            self._id_to_rid[iid] = rid
+            int_ids.append(iid)
+
+        ids = np.array(int_ids, dtype=np.int64)
+        self._index.add_with_ids(normed, ids)
+
+    def search(
+        self,
+        vector: NDArray[np.float32],
+        k: int,
+    ) -> list[SearchHit]:
+        if self._index.ntotal == 0:
+            return []
+
+        q = np.asarray(vector, dtype=np.float32).reshape(1, -1).copy()
+        faiss.normalize_L2(q)
+
+        limit = min(int(k), int(self._index.ntotal))
+        scores, ids = self._index.search(q, limit)
+
+        out: list[SearchHit] = []
+        for iid, score in zip(ids[0], scores[0], strict=False):
+            if int(iid) < 0:
+                continue
+            rid = self._id_to_rid.get(int(iid))
+            if rid is None:
+                continue
+            out.append((rid, float(score)))
+        return out
+
+    def delete(self, rids: list[str]) -> None:
+        if not rids:
+            return
+        int_ids: list[int] = []
+        for rid in rids:
+            srid = str(rid)
+            iid = self._rid_to_id.pop(srid, None)
+            if iid is None:
+                continue
+            self._id_to_rid.pop(iid, None)
+            int_ids.append(iid)
+
+        if int_ids:
+            self._index.remove_ids(np.array(int_ids, dtype=np.int64))
+
+    def flush(self) -> None:
+        self._storage_dir.mkdir(parents=True, exist_ok=True)
+        faiss.write_index(self._index, str(self._index_file))
+
+        payload = {
+            "rid_to_id": self._rid_to_id,
+            "id_to_rid": {str(iid): rid for iid, rid in self._id_to_rid.items()},
+            "next_id": self._next_id,
+        }
+        self._map_file.write_text(
+            json.dumps(payload, ensure_ascii=False),
+            encoding="utf-8",
+        )
+
+    def close(self) -> None:
+        self.flush()

pave/backends/qdrant.py

@@ -0,0 +1,46 @@
+# (C) 2026 Rodrigo Rodrigues da Silva <rodrigo@flowlexi.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .base import SearchHit
+
+
+class QdrantVectorBackend:
+    """Stub for Qdrant vector backend. Not yet implemented."""
+
+    def __init__(
+        self,
+        *,
+        url: str,
+        collection: str,
+        api_key: str | None = None,
+    ) -> None:
+        self._url = url
+        self._collection = collection
+        self._api_key = api_key
+
+    def initialize(self) -> None:
+        raise NotImplementedError("QdrantVectorBackend")
+
+    def add(self, rids: list[str], vectors: NDArray[np.float32]) -> None:
+        raise NotImplementedError("QdrantVectorBackend")
+
+    def search(
+        self,
+        vector: NDArray[np.float32],
+        k: int,
+    ) -> list[SearchHit]:
+        raise NotImplementedError("QdrantVectorBackend")
+
+    def delete(self, rids: list[str]) -> None:
+        raise NotImplementedError("QdrantVectorBackend")
+
+    def flush(self) -> None:
+        raise NotImplementedError("QdrantVectorBackend")
+
+    def close(self) -> None:
+        raise NotImplementedError("QdrantVectorBackend")