epzero 0.4.0__tar.gz → 0.5.0__tar.gz

epzero-0.5.0/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+## 0.5.0
+
+An index that stays accurate as its data changes, fixed in place; metadata and keyword search in the
+engine; LlamaIndex and Haystack beside LangChain; retrieval evaluation; and Windows. Files written by
+0.4 load unchanged.
+
+**Staying accurate after the build.**
+
+- `index.recalibrate(queries)` (C++: `epzero::recalibrate`): re-measures the beam width for the
+  recall target on real queries and saves it in the profile, without rebuilding.
+- `index.health()` (C++: `check_health`): live and deleted vectors, growth since calibration, and how
+  much of the data the principal directions still capture, with advice in plain words: compact,
+  recalibrate, or rebuild.
+- `RecallGuard(index)` takes its target and starting beam width from the profile.
+- `index.check_queries(queries)` (C++: `check_queries`) says whether queries look like the data: text
+  queries against image vectors sit 2.2-2.3× farther from their nearest neighbours than rows of the data,
+  against 0.99-1.09× for queries like the data, and recall calibrated on the data then falls to 0.74-0.80
+  for a 0.95 target. Its advice: `recalibrate(queries)`, which restored 0.945-0.958 on VIBE's
+  text-to-image sets.
+- `index.requantize()` (C++: `HnswIndex::requantize`, then `refine_links`): for vectors added since the
+  build that lie outside the ranges the 8-bit codes were fitted on. It refits the ranges on the live
+  vectors, re-encodes them and reconnects the graph, in about half a rebuild's time; after a 4 sd drift
+  it brought the beam width for recall 0.95 from 200 back to a rebuild's 12. `health()` reports
+  `code_error` and advises it above 0.01.
+- `index.get_vector(label)` returns a stored vector.
+
+**Information retrieval.** `epzero.ir`: a `Collection` of documents with string ids, retrieved by vector,
+by keyword (BM25) or both (reciprocal rank fusion), growing and shrinking after the build; TREC run files
+in and out; relevance judgements in TREC or BEIR form; nDCG@k, MAP, recall, precision and MRR, matching
+trec_eval (tested against it); and a BEIR dataset loader.
+
+**Stemming.** `TextIndex` reduces English words to their Porter stems, so "connections" matches
+"connected" (`stemmer="none"` keeps words as written). It is the reference implementation's algorithm,
+the one Lucene and Anserini use, and agrees with NLTK's on all 39,011 words of SciFact's and NFCorpus's
+vocabularies. nDCG@10 for BM25 went from 0.660 to 0.688 on SciFact and from 0.305 to 0.321 on NFCorpus
+(BEIR's Anserini baselines: 0.665 and 0.325), and for hybrid search with all-MiniLM-L6-v2 from 0.682 to
+0.713 and from 0.344 to 0.354. Stemmed text indexes are saved as text format 2; files saved before load
+unstemmed, as they were written.
+
+**Fixes.** `hybrid_search` searched with a fixed beam width of 64 and the default re-rank, ignoring the
+index's calibrated profile; it now uses the profile unless `ef` is given. Calibration could settle on a
+beam width below k, which only k-sized searches had measured.
+
+**File format 5.** Indexes with a profile or 16-bit vectors are written as version 5; 0.4's version 4
+files are still read (a file written by 0.4.0 is part of the test suite). See `docs/file-format.md`.
+
+**Indexes grow.** `add()` no longer fails when an index is full: it grows the capacity (at least
+doubling), copying the nodes and keeping the graph; `index.reserve(n)` and `index.capacity` do it ahead.
+The LangChain, LlamaIndex and Haystack stores, which rebuilt their whole graph each time they filled, now
+grow in place: loading 40,000 documents in batches of 100 went from 6.0 s to 3.4 s. Searches on other
+threads wait for a growth, which moves the index's memory; with a RecallGuard attached, growing must be
+done beforehand with `reserve()`.
+
+**Metadata in the engine.** `epzero.Metadata` (C++: `MetadataIndex`) keeps str, int, float and bool fields
+per label, with an inverted index per field and ordered numeric values, and `select(where)` returns the
+labels that pass ({field: value}, {field: [values]}, or `$eq`, `$ne`, `$in`, `$nin`, `$gt`, `$gte`, `$lt`,
+`$lte`, `$exists`) for a filtered search. The LangChain store now runs dict filters there instead of
+checking every document in Python. Saved in its own file format, fuzzed in CI.
+
+**Memory.** `half_vectors=True` keeps the full vectors as 16-bit floats: about half an index's memory,
+at some speed (up to 17% on GIST1M) and recall (0.003-0.004 on OpenAI embeddings), so never chosen
+automatically. Full-precision search is 4-9% faster, as vector addresses are resolved once per query.
+
+**LlamaIndex.** `epzero.llamaindex.EpzeroVectorStore` (`pip install "epzero[llamaindex]"`): nodes with
+their text and metadata, filters in the engine, `delete_ref_doc`, and persistence.
+
+**Haystack.** `epzero.haystack.EpzeroDocumentStore` and `EpzeroEmbeddingRetriever`
+(`pip install "epzero[haystack]"`): Haystack filters in the engine where the answer is provably the same,
+and Haystack's document-store test suite passes.
+
+**Windows.** The engine builds with MSVC and its tests run on Windows in CI; wheels for Windows (x64).
+
+**Easier to read.** `Index`, `Metadata`, `TextIndex` and `Database` print what they hold (size, metric,
+compression, calibrated beam width), and shape and name errors say what was passed.
+
+## 0.4.0
+
+**Automatic configuration.** `epzero.build(vectors, metric=...)` (C++: `epzero::build_auto` in
+`epzero/auto.h`) configures an index from its data and the machine it is built on:
+
+- From the data: 8-bit codes, whether to walk the graph on principal directions (at 256 dimensions or
+  more, when few directions hold most of the variance), the build passes, the re-rank, and the beam
+  width (`ef`) that reaches a recall target, calibrated on rows held out of the graph or on queries
+  you pass (`queries=`).
+- From the machine: the prefetch setting, timed on this CPU, and every core.
+- Measured on an Intel Xeon Gold 6226 and an AMD Threadripper PRO 9985WX: as fast as hand-tuned
+  settings (within 1-5%), recall 0.949-0.957 on real queries for a 0.95 target, and 1.3-4.1× Glass's
+  queries per second on GIST1M, OpenAI DBpedia and DEEP10M.
+- Every setting can be fixed instead (`epzero.build(vectors, nav_dim=0, M=32)`, or `epzero.plan()`,
+  edit, build). `index.plan` shows each setting and why it was chosen.
+- The choices are saved inside the index (`IndexProfile`, file format v4), and `search()` uses them
+  when called without settings. A loaded index re-applies its prefetch setting only on the same kind
+  of CPU (`epzero.machine()` names it).
+
+**Faster search and builds.**
+
+- `nav_dim`: walk the graph on 8-bit codes of principal directions, re-ranking with the full vectors.
+  With the other changes here, 2.8-4.2× Glass's queries per second on GIST1M and 1.6-2.7× on OpenAI
+  DBpedia embeddings at equal recall, on Intel and AMD servers.
+- `refine_links()`: a second build pass in which every node searches the finished graph and
+  reconnects; `fill_free_links()` gives free link slots to two-hop neighbours.
+- `fast_build`: build on the 8-bit codes.
+- `rerank_z`: stop the re-rank early once the remaining candidates can't reach the top k.
+- Queries are projected onto principal directions on the integer kernel; the AVX2 and AVX-VNNI integer
+  kernels finish with vector loads instead of a scalar tail.
+- The prefetch tuner can fetch a record's every cache line; on a Xeon Gold 6226 that was worth up to
+  1.7× on some datasets.
+- PCA runs as blocked matrix products (choosing directions 5× faster on GIST1M), training runs on
+  every core, and index memory is zeroed on every core, which spreads it across NUMA nodes.
+
+**Fixes.**
+
+- `Database`: a write that could not be applied (the database full, or not yet trained) was written to
+  the log first, after which every open failed replaying it. Writes are now checked before they are
+  logged, and replacing a vector in a full database frees its slot before compacting.
+- `RecallGuard` searched, and measured its reference, with the default re-rank depth; it now uses the
+  index's own settings and re-ranks the reference's whole beam. `explain()` and `trace()` likewise.
+- The LangChain store copied every stored vector on each add (quadratic in the store's size).
+- `pip install epzero` from source failed on machines with gRPC installed: it tried to build the
+  cluster node, whose protocol files aren't in the package.
+
+**Compatibility.** Indexes without a profile are still written in the format older versions read
+(v2, or v3 with principal directions); automatically configured ones are v4, which 0.3 cannot load.
+`search()`'s `k`, `ef`, `rerank` and `rerank_z` now default to the index's profile, which for an index
+built by hand is the old defaults (10, 64, 2 × k, off).
+
+Earlier releases are described by their git tags (`v0.2.0`, `v0.3.0`).

{epzero-0.4.0 → epzero-0.5.0}/CMakeLists.txt

@@ -52,6 +52,7 @@ add_library(epzero_engine
   src/distance.cpp
   src/distance_scalar.cpp
   src/hnsw.cpp
+  src/metadata.cpp
   src/recall.cpp
   src/database.cpp
   src/text.cpp
@@ -60,20 +61,38 @@ add_library(epzero_engine
 )
 target_include_directories(epzero_engine PUBLIC include PRIVATE src)
 target_link_libraries(epzero_engine PUBLIC Threads::Threads)
-target_compile_options(epzero_engine PRIVATE -Wall -Wextra -Wpedantic)
+if(MSVC)
+  target_compile_options(epzero_engine PRIVATE /W3 /utf-8 /permissive- /Zc:__cplusplus)
+  target_compile_definitions(epzero_engine PRIVATE _CRT_SECURE_NO_WARNINGS NOMINMAX)
+else()
+  target_compile_options(epzero_engine PRIVATE -Wall -Wextra -Wpedantic)
+endif()
 set_target_properties(epzero_engine PROPERTIES POSITION_INDEPENDENT_CODE ON)
 
 # SIMD kernels get ISA flags per file; the rest of the library stays baseline so the binary
 # runs on any CPU of the architecture and picks the best kernel at runtime.
 if(CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|AMD64|amd64")
-  target_sources(epzero_engine PRIVATE src/distance_avx2.cpp src/distance_avx512.cpp)
-  set_source_files_properties(src/distance_avx2.cpp PROPERTIES COMPILE_OPTIONS "-mavx2;-mfma;-mpopcnt")
-  set_source_files_properties(src/distance_avx512.cpp PROPERTIES COMPILE_OPTIONS "-mavx512f")
+  target_sources(epzero_engine PRIVATE src/distance_avx2.cpp src/distance_avx512.cpp src/distance_f16c.cpp)
+  if(MSVC)  # MSVC allows any intrinsic; /arch only lets the compiler use the ISA on its own
+    set_source_files_properties(src/distance_f16c.cpp src/distance_avx2.cpp PROPERTIES COMPILE_OPTIONS "/arch:AVX2")
+    set_source_files_properties(src/distance_avx512.cpp PROPERTIES COMPILE_OPTIONS "/arch:AVX512")
+  else()
+    set_source_files_properties(src/distance_f16c.cpp PROPERTIES COMPILE_OPTIONS "-mavx2;-mfma;-mf16c")
+    set_source_files_properties(src/distance_avx2.cpp PROPERTIES COMPILE_OPTIONS "-mavx2;-mfma;-mpopcnt")
+    set_source_files_properties(src/distance_avx512.cpp PROPERTIES COMPILE_OPTIONS "-mavx512f")
+  endif()
   # VNNI integer kernels, where the toolchain can build them: the compiler must know the
   # instructions (GCC 11+, Clang 12+ for AVX-VNNI) and so must the assembler it hands them to
   # (binutils 2.36+ for AVX-VNNI; RHEL 9's 2.35 doesn't), so each check compiles and links a use.
   include(CheckCXXSourceCompiles)
-  set(CMAKE_REQUIRED_FLAGS "-mavx2 -mavxvnni")
+  if(MSVC)
+    set(EPZERO_AVXVNNI_FLAGS "/arch:AVX2")
+    set(EPZERO_AVX512VNNI_FLAGS "/arch:AVX512")
+  else()
+    set(EPZERO_AVXVNNI_FLAGS "-mavx2 -mavxvnni")
+    set(EPZERO_AVX512VNNI_FLAGS "-mavx512f -mavx512bw -mavx512vnni")
+  endif()
+  set(CMAKE_REQUIRED_FLAGS "${EPZERO_AVXVNNI_FLAGS}")
   check_cxx_source_compiles([[
     #include <immintrin.h>
     int main(int argc, char**) {
@@ -81,7 +100,7 @@ if(CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|AMD64|amd64")
       a = _mm256_dpbusd_avx_epi32(a, a, a);
       return _mm256_extract_epi32(a, 0);
     }]] EPZERO_TOOLCHAIN_AVXVNNI)
-  set(CMAKE_REQUIRED_FLAGS "-mavx512f -mavx512bw -mavx512vnni")
+  set(CMAKE_REQUIRED_FLAGS "${EPZERO_AVX512VNNI_FLAGS}")
   check_cxx_source_compiles([[
     #include <immintrin.h>
     int main(int argc, char**) {
@@ -92,12 +111,14 @@ if(CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|AMD64|amd64")
   unset(CMAKE_REQUIRED_FLAGS)
   if(EPZERO_TOOLCHAIN_AVXVNNI)
     target_sources(epzero_engine PRIVATE src/distance_avxvnni.cpp)
-    set_source_files_properties(src/distance_avxvnni.cpp PROPERTIES COMPILE_OPTIONS "-mavx2;-mavxvnni")
+    string(REPLACE " " ";" flags "${EPZERO_AVXVNNI_FLAGS}")
+    set_source_files_properties(src/distance_avxvnni.cpp PROPERTIES COMPILE_OPTIONS "${flags}")
     set_property(SOURCE src/distance.cpp APPEND PROPERTY COMPILE_DEFINITIONS EPZERO_HAVE_AVXVNNI)
   endif()
   if(EPZERO_TOOLCHAIN_AVX512VNNI)
     target_sources(epzero_engine PRIVATE src/distance_avx512vnni.cpp)
-    set_source_files_properties(src/distance_avx512vnni.cpp PROPERTIES COMPILE_OPTIONS "-mavx512f;-mavx512bw;-mavx512vnni")
+    string(REPLACE " " ";" flags "${EPZERO_AVX512VNNI_FLAGS}")
+    set_source_files_properties(src/distance_avx512vnni.cpp PROPERTIES COMPILE_OPTIONS "${flags}")
     set_property(SOURCE src/distance.cpp APPEND PROPERTY COMPILE_DEFINITIONS EPZERO_HAVE_AVX512VNNI)
   endif()
 elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64|arm64")
@@ -119,8 +140,9 @@ if(EPZERO_BUILD_TESTS)
   FetchContent_MakeAvailable(googletest)
 
   enable_testing()
-  add_executable(epzero_tests tests/auto_test.cpp tests/distance_test.cpp tests/hnsw_test.cpp tests/recall_test.cpp tests/dataset_test.cpp tests/database_test.cpp tests/text_test.cpp)
+  add_executable(epzero_tests tests/auto_test.cpp tests/distance_test.cpp tests/half_test.cpp tests/hnsw_test.cpp tests/metadata_test.cpp tests/recall_test.cpp tests/dataset_test.cpp tests/database_test.cpp tests/text_test.cpp)
   target_link_libraries(epzero_tests PRIVATE epzero_engine GTest::gtest_main)
+  target_compile_definitions(epzero_tests PRIVATE EPZERO_TEST_DATA="${CMAKE_CURRENT_SOURCE_DIR}/tests/data")
   if(EMSCRIPTEN)
     # Runs under Node (CMAKE_CROSSCOMPILING_EMULATOR); workers are pre-spawned for the
     # concurrency tests and the real filesystem backs the save/load tests.
@@ -146,7 +168,7 @@ if(EPZERO_BUILD_BENCH)
 endif()
 
 if(EPZERO_BUILD_FUZZ)
-  foreach(target snapshot graph wal text)
+  foreach(target snapshot graph wal text metadata)
     add_executable(fuzz_${target} fuzz/fuzz_${target}.cpp)
     target_link_libraries(fuzz_${target} PRIVATE epzero_engine)
     target_link_options(fuzz_${target} PRIVATE -fsanitize=fuzzer)
@@ -193,20 +215,26 @@ if(EPZERO_BUILD_NODE AND NOT EMSCRIPTEN)
 endif()
 
 if(EMSCRIPTEN)
-  # ES module for the browser demo: `import createEpzero from "./epzero.js"`.
-  add_executable(epzero_web wasm/epzero_wasm.cpp)
-  target_link_libraries(epzero_web PRIVATE epzero_engine)
+  # ES modules for the browser demo: `import createEpzero from "./epzero.js"`. epzero-lab.js adds the
+  # automatic configuration (build_auto) for the benchmark lab, which is 36 KB more compressed: kept out
+  # of the module every other page loads first.
+  foreach(web_target epzero_web epzero_lab)
+    add_executable(${web_target} wasm/epzero_wasm.cpp)
+    target_link_libraries(${web_target} PRIVATE epzero_engine)
+    target_link_options(${web_target} PRIVATE
+      -lembind -sMODULARIZE=1 -sEXPORT_ES6=1 -sEXPORT_NAME=createEpzero -sENVIRONMENT=web,worker -sSTACK_SIZE=1MB
+      # No eval / new Function in the generated bindings, so the site's Content Security Policy can
+      # forbid it (only WebAssembly compilation is allowed).
+      -sDYNAMIC_EXECUTION=0)
+    if(EPZERO_WASM_THREADS)
+      # Pre-spawn the workers: the module's own thread blocks while a build runs, so it cannot
+      # create new ones on demand.
+      target_link_options(${web_target} PRIVATE "-sPTHREAD_POOL_SIZE=Math.min(navigator.hardwareConcurrency,16)")
+    endif()
+  endforeach()
   set_target_properties(epzero_web PROPERTIES OUTPUT_NAME epzero SUFFIX .js)
-  target_link_options(epzero_web PRIVATE
-    -lembind -sMODULARIZE=1 -sEXPORT_ES6=1 -sEXPORT_NAME=createEpzero -sENVIRONMENT=web,worker -sSTACK_SIZE=1MB
-    # No eval / new Function in the generated bindings, so the site's Content Security Policy can
-    # forbid it (only WebAssembly compilation is allowed).
-    -sDYNAMIC_EXECUTION=0)
-  if(EPZERO_WASM_THREADS)
-    # Pre-spawn the workers: the module's own thread blocks while a build runs, so it cannot
-    # create new ones on demand.
-    target_link_options(epzero_web PRIVATE "-sPTHREAD_POOL_SIZE=Math.min(navigator.hardwareConcurrency,16)")
-  endif()
+  set_target_properties(epzero_lab PROPERTIES OUTPUT_NAME epzero-lab SUFFIX .js)
+  target_compile_definitions(epzero_lab PRIVATE EPZERO_WASM_LAB_AUTO=1)
 endif()
 
 if(EPZERO_BUILD_PYTHON)

{epzero-0.4.0 → epzero-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: epzero
-Version: 0.4.0
+Version: 0.5.0
 Summary: A fast HNSW vector database in C++20 that configures itself: SIMD search, filtered search, recall monitoring, crash-safe storage
 Keywords: vector database,hnsw,ann,nearest neighbor,embeddings,rag,langchain
 Author: Lajat
@@ -12,6 +12,7 @@ Classifier: Programming Language :: C++
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
 Classifier: Topic :: Database
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Project-URL: Homepage, https://epzero.dev/
@@ -20,11 +21,17 @@ Requires-Python: >=3.10
 Requires-Dist: numpy
 Provides-Extra: langchain
 Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.12; extra == "llamaindex"
+Provides-Extra: haystack
+Requires-Dist: haystack-ai>=2.10; extra == "haystack"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-asyncio; extra == "test"
 Requires-Dist: langchain-core>=0.3; extra == "test"
 Requires-Dist: langchain-tests>=0.3; extra == "test"
+Requires-Dist: llama-index-core>=0.12; extra == "test"
+Requires-Dist: haystack-ai>=2.10; extra == "test"
 Description-Content-Type: text/markdown
 
 # epzero
@@ -45,16 +52,24 @@ An HNSW vector database written from scratch in C++20, with Python bindings.
   confidence interval and moves the search effort to hold a target; `explain()` says why any given
   item was not returned. With `per_query=True` each query also stops as soon as its answer settles,
   so easy queries cost less and hard ones search further.
-- **Hybrid search:** `TextIndex` (BM25 keyword search) and `hybrid_search()`, which merges it
-  with vector search by reciprocal rank fusion.
+- **Hybrid search:** `TextIndex` (BM25 keyword search, with English stemming) and `hybrid_search()`,
+  which merges it with vector search by reciprocal rank fusion.
+- **Retrieval evaluation:** `epzero.ir` keeps documents under string ids, runs dense, keyword and
+  hybrid retrieval, writes TREC run files and scores them against relevance judgements exactly as
+  trec_eval does. On BEIR with all-MiniLM-L6-v2, hybrid reaches nDCG@10 0.713 on SciFact and 0.354 on
+  NFCorpus, above either half alone.
 - **Durable:** `Database` adds a write-ahead log with crash recovery and checkpoints.
 - **8-bit quantization** with exact re-ranking, stopped early per query once the rest can't reach
   the top k.
-- **A LangChain vector store** in `epzero.langchain`.
+- **Stays accurate as data changes:** `health()` says when an index needs recalibrating,
+  requantizing, compacting or rebuilding, and each fix runs in place.
+- **LangChain, LlamaIndex and Haystack** stores, each passing its framework's own test suite.
 
 ```bash
 pip install epzero                 # the engine
 pip install "epzero[langchain]"    # plus the LangChain vector store
+pip install "epzero[llamaindex]"   # plus the LlamaIndex vector store
+pip install "epzero[haystack]"     # plus the Haystack document store and retriever
 ```
 
 ## Quick start: let it configure itself
@@ -93,12 +108,36 @@ users get the same `build_auto()`.
 If your queries differ from your data (text queries against image vectors, say), pass a few
 hundred of them as `queries=`: recall calibrated on data rows is optimistic for those.
 
+**Metadata.** Fields per label, filtered in the engine:
+
+```python
+meta = epzero.Metadata()
+meta.set_many(labels, [{"source": "faq", "year": 2024}, ...])
+allowed = meta.select({"source": ["faq", "docs"], "year": {"$gte": 2022}})
+labels, distances = index.search(queries, k=10, filter=index.filter(allowed))
+```
+
+**After the build.** An index keeps changing; its calibration doesn't, by itself:
+
+```python
+print(index.health())          # growth since calibration, deleted share, code error, fit of the directions, advice
+print(index.check_queries(queries))   # do these queries look like the data? (text vs images: no)
+index.recalibrate(queries)     # re-measure the beam width on real queries; saved in the profile
+index.requantize()             # vectors drifted outside the 8-bit codes' ranges: refit and reconnect
+guard = epzero.RecallGuard(index, sample_rate=0.01)   # or measure live recall and adjust as you go
+```
+
+When later vectors drift outside the ranges the 8-bit codes were fitted on, they are clipped and
+the graph links chosen for them suffer: in a synthetic test with a 4 sd drift, the beam width needed
+for recall 0.95 went from 12 to 200. `requantize()` refits the codes and reconnects the graph in about half a rebuild's
+time, back to 12.
+
 ## Configured by hand
 
 ```python
 vectors = np.random.rand(100_000, 128).astype(np.float32)
 index = epzero.Index(dim=128, metric="l2", max_elements=100_000, M=16, ef_construction=200)
-index.add(vectors)                                   # labels 0..n-1 (or pass labels=)
+index.add(vectors)                                   # labels 0..n-1 (or pass labels=); grows as needed
 
 labels, distances = index.search(vectors[:5], k=10, ef=64)
 
@@ -145,9 +184,59 @@ metadata. They are compiled into an Epzero filter, so the engine chooses how to
 documents instead of over-fetching and discarding. The store passes LangChain's standard
 vector-store test suite.
 
+## LlamaIndex
+
+```python
+from llama_index.core import StorageContext, VectorStoreIndex
+from epzero.llamaindex import EpzeroVectorStore
+
+store = EpzeroVectorStore(metric="cosine")
+index = VectorStoreIndex.from_documents(documents, storage_context=StorageContext.from_defaults(vector_store=store))
+index.as_query_engine().query("How do I reset my password?")
+store.persist("./epzero-store")        # EpzeroVectorStore.from_persist_path("./epzero-store")
+```
+
+Metadata filters (`==`, `!=`, `>`, `>=`, `<`, `<=`, `in`, `nin`, combined with AND or OR) run in the
+engine, as do `doc_ids` and `node_ids`; `delete_ref_doc` removes a document's nodes.
+
+## Haystack
+
+```python
+from haystack import Pipeline
+from epzero.haystack import EpzeroDocumentStore, EpzeroEmbeddingRetriever
+
+store = EpzeroDocumentStore(metric="cosine")
+store.write_documents(documents)       # Documents with embeddings
+pipeline = Pipeline()
+pipeline.add_component("retriever", EpzeroEmbeddingRetriever(document_store=store, top_k=5))
+pipeline.run({"retriever": {"query_embedding": embedding,
+                            "filters": {"field": "meta.lang", "operator": "==", "value": "en"}}})
+```
+
+Filters use Haystack's syntax and run in the engine wherever that gives exactly Haystack's answer;
+the rest (ranges on dates, `None`) go to Haystack's reference implementation. The store passes
+Haystack's document-store test suite.
+
+## Retrieval evaluation
+
+```python
+from epzero import ir
+
+corpus, queries, qrels = ir.load_beir("scifact")              # a BEIR dataset folder
+collection = ir.Collection.build(list(corpus), doc_vectors, texts=list(corpus.values()), metric="cosine")
+run = collection.retrieve(list(queries), vectors=query_vectors, texts=list(queries.values()),
+                          k=100, mode="hybrid")                # or "dense", "keyword"
+ir.write_run(run, "run.txt", tag="my-system")                  # TREC format, for CLEF or TREC
+print(ir.evaluate(run, qrels))                                 # nDCG@10, R@100, MAP, MRR@10
+```
+
+`evaluate` matches trec_eval (tested against it, ties included) and also takes `per_query=True` and
+measures like `P@5` or `nDCG@20`. Documents can be added, replaced and removed by id, and a collection
+saves to a folder.
+
 ## Platforms
 
-Wheels for Linux (x86-64 and ARM64, glibc 2.28+) and macOS (Apple silicon and Intel), Python 3.10
-to 3.13. Elsewhere, `pip install epzero` builds from source (CMake 3.20+, a C++20 compiler).
+Wheels for Linux (x86-64 and ARM64, glibc 2.28+), macOS (Apple silicon and Intel) and, from 0.5,
+Windows (x64), Python 3.10 to 3.13. Elsewhere, `pip install epzero` builds from source (CMake 3.20+, a C++20 compiler).
 
 Live demo, benchmarks and design notes: https://epzero.dev/ · MIT license.

{epzero-0.4.0 → epzero-0.5.0}/bench/bench_recall.cpp

@@ -43,6 +43,7 @@ struct Options {
   std::size_t nav_dim = 0;
   bool fill_links = false;
   bool fast_build = false;
+  bool half = false;
   bool fill_after = false;
   std::size_t refine = 0;
   bool refine_exact = false;
@@ -98,6 +99,7 @@ Options parse(int argc, char** argv) {
     else if (arg == "--nav-dim") o.nav_dim = std::stoul(value());
     else if (arg == "--fill-links") o.fill_links = true;
     else if (arg == "--fast-build") o.fast_build = true;
+    else if (arg == "--half") o.half = true;
     else if (arg == "--fill-after") o.fill_after = true;
     else if (arg == "--refine") o.refine = std::stoul(value());
     else if (arg == "--refine-exact") o.refine_exact = true;
@@ -191,7 +193,7 @@ int main(int argc, char** argv) try {
     HnswParams params{.dim = dim, .metric = opt.metric, .max_elements = base.n, .M = opt.M,
                       .ef_construction = opt.ef_construction, .seed = opt.seed, .quantization = opt.quantization,
                       .keep_vectors = opt.keep_vectors, .nav_dim = opt.nav_dim, .fill_links = opt.fill_links,
-                      .fast_build = opt.fast_build};
+                      .fast_build = opt.fast_build, .half_vectors = opt.half};
     loaded = std::make_unique<HnswIndex>(params);
     t0 = Clock::now();
     loaded->train(base.data.data(), std::min<std::size_t>(base.n, 100'000));  // no-op unquantized

epzero-0.5.0/bench/regression.json

@@ -0,0 +1,58 @@
+{
+  "float-l2": {
+    "4": {
+      "recall": 0.9068,
+      "distances": 209.99
+    },
+    "8": {
+      "recall": 0.9068,
+      "distances": 209.99
+    },
+    "16": {
+      "recall": 0.9664,
+      "distances": 247.212
+    }
+  },
+  "float-cosine": {
+    "4": {
+      "recall": 0.9042,
+      "distances": 222.262
+    },
+    "8": {
+      "recall": 0.9042,
+      "distances": 222.262
+    },
+    "16": {
+      "recall": 0.967,
+      "distances": 263.986
+    }
+  },
+  "sq8-second-pass": {
+    "4": {
+      "recall": 0.9132,
+      "distances": 234.102
+    },
+    "8": {
+      "recall": 0.9132,
+      "distances": 234.102
+    },
+    "16": {
+      "recall": 0.981,
+      "distances": 275.388
+    }
+  },
+  "sq8-directions": {
+    "32": {
+      "recall": 0.4988,
+      "distances": 323.592
+    },
+    "64": {
+      "recall": 0.7316,
+      "distances": 390.994
+    },
+    "128": {
+      "recall": 0.9518,
+      "distances": 508.41
+    }
+  }
+}

epzero-0.5.0/fuzz/fuzz_metadata.cpp

@@ -0,0 +1,23 @@
+// Fuzzes MetadataIndex::load: arbitrary bytes as a metadata file must either load into an index that is
+// safe to query, change and save, or throw. Never crash, read out of bounds or hit undefined behavior.
+#include <exception>
+#include <string>
+
+#include "common.h"
+#include "epzero/metadata.h"
+
+extern "C" int LLVMFuzzerTestOneInput(const std::uint8_t* data, std::size_t size) {
+  static const auto path = epzero::fuzz::scratch("metadata") / "input.meta";
+  epzero::fuzz::write_bytes(path, data, size);
+  try {
+    epzero::MetadataIndex index = epzero::MetadataIndex::load(path.string());
+    (void)index.select({{.field = "source", .any_of = {std::string("faq")}}, {.field = "year", .min = 2000.0}});
+    (void)index.select({{.field = "year", .max = 1e9, .negate = true}});
+    index.set(1, {{"source", std::string("new")}});
+    index.remove(1);
+    index.save(path.string());
+  } catch (const std::exception&) {
+    // Rejected cleanly: the expected outcome for corrupt input.
+  }
+  return 0;
+}

{epzero-0.4.0 → epzero-0.5.0}/fuzz/make_seeds.cpp

@@ -9,6 +9,7 @@
 
 #include "common.h"
 #include "epzero/database.h"
+#include "epzero/metadata.h"
 #include "epzero/text.h"
 
 namespace fs = std::filesystem;
@@ -20,7 +21,7 @@ int main(int argc, char** argv) {
     return 2;
   }
   const fs::path out = argv[1];
-  for (const char* name : {"snapshot", "graph", "wal", "text"}) fs::create_directories(out / name);
+  for (const char* name : {"snapshot", "graph", "wal", "text", "metadata"}) fs::create_directories(out / name);
 
   std::vector<float> vectors(40 * kDim);
   for (std::size_t i = 0; i < vectors.size(); ++i) vectors[i] = static_cast<float>((i * 7919) % 101) / 101.0f;
@@ -68,7 +69,16 @@ int main(int argc, char** argv) {
   text.add(1, "red car by the river");
   text.add(2, "night city lights, city traffic");
   text.add(7, "café über 42");
-  text.save((out / "text" / "valid").string());
+  text.save((out / "text" / "valid").string());  // version 2: stemmed
+  epzero::TextIndex plain({.stemmer = epzero::TextIndex::Stemmer::None});
+  plain.add(1, "red car by the river");
+  plain.add(7, "café über 42");
+  plain.save((out / "text" / "valid-v1").string());
+
+  epzero::MetadataIndex meta;
+  meta.set(1, {{"source", std::string("faq")}, {"year", std::int64_t{2021}}, {"public", true}});
+  meta.set(2, {{"source", std::string("blog")}, {"score", 0.5}});
+  meta.save((out / "metadata" / "valid").string());
   std::printf("seeds written to %s\n", out.string().c_str());
   return 0;
 }

{epzero-0.4.0 → epzero-0.5.0}/include/epzero/auto.h

@@ -18,7 +18,9 @@
 #include <cstdint>
 #include <memory>
 #include <optional>
+#include <string>
 #include <utility>
+#include <vector>
 
 #include "epzero/hnsw.h"
 
@@ -35,6 +37,7 @@ struct AutoFixed {
   std::optional<float> rerank_z;
   std::optional<std::size_t> ef;   // skips calibration
   std::optional<std::pair<std::size_t, std::size_t>> prefetch;  // (depth, lines); skips timing
+  std::optional<bool> half_vectors;  // 16-bit full vectors: half their memory (never chosen automatically)
 };
 
 struct AutoOptions {
@@ -67,4 +70,40 @@ AutoPlan plan_auto(const float* data, std::size_t n, std::size_t dim, const Auto
 std::unique_ptr<HnswIndex> build_auto(const float* data, const std::uint64_t* labels, std::size_t n, std::size_t dim,
                                       const AutoOptions& options = {});
 
+// Re-measures the beam width that reaches `recall` (0: the profile's target, else 0.95) on `queries`
+// (count rows of dim floats) and stores it in the index's profile, which search() then uses. Pass real
+// queries: rows already in the graph are linked to their own neighbours, so they make the search look
+// easier than it is. Not thread-safe against concurrent searches. Returns (ef, recall reached).
+std::pair<std::size_t, float> recalibrate(HnswIndex& index, const float* queries, std::size_t count, float recall = 0.0f,
+                                          std::size_t threads = 0);
+
+// What an index needs, if anything, since it was built: a measurement plus advice in plain words.
+struct IndexHealth {
+  std::size_t live = 0;
+  std::size_t deleted = 0;          // tombstones still in the graph
+  double growth = 0.0;              // change in live vectors since calibration, as a share (0.3: 30% more)
+  double nav_variance_built = 0.0;  // share of the variance the principal directions held when built
+  double nav_variance_now = 0.0;    // and on the vectors in the index now (0 without principal directions)
+  double code_error = 0.0;          // share of the variance the 8-bit codes miss (HnswIndex::code_error)
+  std::vector<std::string> advice;  // empty when nothing needs doing
+};
+IndexHealth check_health(const HnswIndex& index, std::size_t threads = 0);
+
+// Whether `queries` (count rows) look like the data the index was calibrated on. A query from the data's
+// distribution sits about as far from its nearest neighbour as rows of the data do from theirs; text
+// queries against image vectors, say, sit far farther (VIBE's text-to-image sets: 2.3x, against 0.99-1.09x
+// for queries like the data). Then recall calibrated on rows of the data overestimates theirs (0.74-0.80
+// against a 0.95 target on those sets), and `advice` says to recalibrate on them.
+struct QueryCheck {
+  double query_distance = 0.0;  // median distance from a query to its nearest neighbour (sample)
+  double row_distance = 0.0;    // the same for rows of the data
+  double ratio = 0.0;           // query_distance / row_distance
+  bool shifted = false;         // ratio above 1.5
+  std::vector<std::string> advice;
+};
+QueryCheck check_queries(const HnswIndex& index, const float* queries, std::size_t count, std::size_t threads = 0);
+
+// Share of the variance of the index's vectors (a sample) that its principal directions hold.
+double nav_variance(const HnswIndex& index, std::size_t threads = 0);
+
 }  // namespace epzero

{epzero-0.4.0 → epzero-0.5.0}/include/epzero/distance.h

@@ -38,6 +38,12 @@ std::string machine_name();
 DistanceFn get_distance_fn(Metric metric, SimdLevel level) noexcept;
 DistanceFn get_distance_fn(Metric metric) noexcept;
 
+// A float query against a vector stored as IEEE half floats (HnswParams::half_vectors): the metric's
+// distance as get_distance_fn computes it. Always available (a scalar fallback); F16C or NEON where
+// the CPU has them.
+using HalfDistanceFn = float (*)(const float* query, const std::uint16_t* v, std::size_t dim) noexcept;
+HalfDistanceFn get_half_distance_fn(Metric metric, SimdLevel level) noexcept;
+
 // Asymmetric-distance kernel for 8-bit scalar quantization: returns sum_i w[i] * codes[i].
 // The quantizer folds its per-dimension scales and offsets into `w` once per query, so scoring a
 // node reads only `dim` bytes. Returns nullptr if `level` is not supported.