tobogganSe connecter

packages

The Louise packages, each released on its own

Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.

NomDernier commitDate
bench/Packages: vectors, packed f32 rows ranked by a C top-k kernelil y a 5 j
csrc/Packages: vectors, packed f32 rows ranked by a C top-k kernelil y a 5 j
src/Packages: vectors, packed f32 rows ranked by a C top-k kernelil y a 5 j
test/Packages: vectors, packed f32 rows ranked by a C top-k kernelil y a 5 j
CHANGELOG.mdA repository of its own: README, CI, release checks, fixturesil y a 4 j
louise.tomlVersion every package 0.21.0, on louise 0.22.0il y a 4 j
README.mdPackages: vectors, packed f32 rows ranked by a C top-k kernelil y a 5 j
README.MD

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

FunctionResult
from_bytes dim dataResult<Vectors, String>: refuses a dim below 1, partial rows, NaN and infinities
from_base64 dim text, from_floats dim xsthe same, from base64 or Floats (rounded to single precision)
empty dimno rows
dim v, count vfloats per row, rows
to_bytes v, to_base64 vthe packed form, back
row v iOption<List<Float>>
rows v start endrows start..end, clamped
concat a b, concat_all dim partsResult<Vectors, String>: Error when dimensions differ
dot a i b jFloat: row i of a with row j of b
top_k matrix query kList<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_k reads every row once and keeps the best k in 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 so std/bytes can read them. lib.lse turns them into Hits.
  • 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_len and tl_bytes_from from louise_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.