vectors
Packed float vectors, ranked with a C kernel: the exact nearest-neighbour
step of semantic search. Rows of dim 32-bit floats are stored packed and
little-endian in Bytes, which is how embedding services send them (base64
in JSON) and how a database can store them (a bytea).
import vectors
let index = vectors.from_base64 384 text // Ok(Vectors) or Error(reason)
let query = vectors.from_floats 384 numbers
vectors.top_k index query 10 // [Hit(row: 7, score: 0.83), ...]
Unit vectors (L2-normalised) make the dot product their cosine similarity. This package does not normalise them.
API
| Function | Result |
|---|---|
from_bytes dim data | Result<Vectors, String>: refuses a dim below 1, partial rows, NaN and infinities |
from_base64 dim text, from_floats dim xs | the same, from base64 or Floats (rounded to single precision) |
empty dim | no rows |
dim v, count v | floats per row, rows |
to_bytes v, to_base64 v | the packed form, back |
row v i | Option<List<Float>> |
rows v start end | rows start..end, clamped |
concat a b, concat_all dim parts | Result<Vectors, String>: Error when dimensions differ |
dot a i b j | Float: row i of a with row j of b |
top_k matrix query k | List<Hit>: the k best rows, best first, ties by row |
Every function that reads floats performs <ffi>. top_k and the checks
in from_bytes run on the cpu blocking pool (ADR 0005, Revision 2).
Design
- Exact, not approximate.
top_kreads every row once and keeps the bestkin a heap.bench/measures about 10 ms for 100,000 rows of 384 (x86-64, one core). That is close to memory bandwidth, and enough for an index of tens of thousands of notes. An approximate index (HNSW, IVF) would be a separate package. - Single precision. Scores are computed in
float, using eight partial sums that the compiler vectorises. The order of additions is fixed, so a score does not depend on the build. - Results cross as
Bytes. The kernel returns 8 bytes per hit: the row, then the score's single-precision bits, both big-endian sostd/bytescan read them.lib.lseturns them intoHits. - Little-endian hosts only. The kernel reads floats in place, and a
big-endian target fails to compile (
#error). - Needs
tl_bytes_ptr,tl_bytes_lenandtl_bytes_fromfromlouise_rt.h.
Native-only
The interpreter cannot call C, so run the tests with louise test --native.
They check shapes and errors, and property-test top_k against a naive
Louise ranking: 200 random cases per run, with the seed reported on failure.