Skip to main content

scann_core/
lib.rs

1// Copyright 2026 Elias Benali (@ebenali) and TheCleaners.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Rust bindings for scann-core, the TensorFlow- and Python-independent core
16//! of [ScaNN](https://github.com/google-research/google-research/tree/master/scann).
17//!
18//! Two types do the work:
19//!
20//! * [`ConfigBuilder`] turns high-level options into a ScaNN config, like
21//!   `scann.scann_ops_pybind.builder(...)` in Python (it is the same builder
22//!   ported to C++; see `core/scann_core/config_builder.h`).
23//! * [`ScannIndex`] is a built, searchable, mutable index.
24//!
25//! ```no_run
26//! use scann_core::{AhOptions, ConfigBuilder, DistanceMeasure, ReorderOptions,
27//!                  SearchOptions, TreeOptions};
28//!
29//! # fn main() -> Result<(), scann_core::ScannError> {
30//! let dim = 128;
31//! let dataset: Vec<f32> = vec![0.0; 10_000 * dim]; // row-major, n x dim
32//! let index = ConfigBuilder::new(10, DistanceMeasure::DotProduct, dim)
33//!     .tree(TreeOptions::new(100, 10))
34//!     .score_ah(AhOptions::new(2).anisotropic_quantization_threshold(0.2))
35//!     .reorder(ReorderOptions::new(100))
36//!     .build_index(&dataset)?;
37//! let neighbors = index.search(&dataset[..dim], SearchOptions::default())?;
38//! println!("{:?}", neighbors.indices);
39//! # Ok(())
40//! # }
41//! ```
42//!
43//! Distances are reported the way the Python API reports them: dot product
44//! as the (positive) inner product, squared L2 as the squared distance (also
45//! through [`ConfigBuilder::l2_as_dot_product`]).
46
47mod bridge;
48
49use std::collections::{HashMap, HashSet};
50use std::fmt;
51use std::path::Path;
52use std::sync::Mutex;
53
54use bridge::ffi;
55
56pub use ffi::{HealthStats, Neighbors};
57
58/// Error from scann-core, or from argument validation in these bindings.
59#[derive(Debug, Clone, PartialEq, Eq)]
60pub enum ScannError {
61    /// Rejected by the bindings before reaching C++ (shape mismatch, value
62    /// out of range, ...).
63    InvalidArgument(String),
64    /// A non-OK `absl::Status` (or C++ exception) from scann-core.
65    Scann(String),
66}
67
68impl fmt::Display for ScannError {
69    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
70        match self {
71            ScannError::InvalidArgument(m) => write!(f, "invalid argument: {m}"),
72            ScannError::Scann(m) => write!(f, "{m}"),
73        }
74    }
75}
76
77impl std::error::Error for ScannError {}
78
79impl From<cxx::Exception> for ScannError {
80    fn from(e: cxx::Exception) -> Self {
81        ScannError::Scann(e.what().to_string())
82    }
83}
84
85pub type Result<T, E = ScannError> = std::result::Result<T, E>;
86
87fn invalid<T>(msg: impl Into<String>) -> Result<T> {
88    Err(ScannError::InvalidArgument(msg.into()))
89}
90
91/// `Some(n)` -> n as i32; `None` -> -1 (scann-core's "use the default").
92fn opt_i32(v: Option<usize>, what: &str) -> Result<i32> {
93    match v {
94        None => Ok(-1),
95        Some(n) => i32::try_from(n).or_else(|_| invalid(format!("{what} = {n} does not fit in i32"))),
96    }
97}
98
99fn to_i32(n: usize, what: &str) -> Result<i32> {
100    i32::try_from(n).or_else(|_| invalid(format!("{what} = {n} does not fit in i32")))
101}
102
103/// Number of rows in a row-major `rows x dim` buffer.
104fn rows(data: &[f32], dim: usize, what: &str) -> Result<usize> {
105    if dim == 0 {
106        return invalid("dimensionality must be > 0");
107    }
108    if !data.len().is_multiple_of(dim) {
109        return invalid(format!(
110            "{what}: {} floats is not a multiple of the dimensionality {dim}",
111            data.len()
112        ));
113    }
114    Ok(data.len() / dim)
115}
116
117// ---------------------------------------------------------------------------
118// Search
119// ---------------------------------------------------------------------------
120
121/// Per-query search overrides. `None` uses the value from the config the
122/// index was built with (Python: passing `None`).
123#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
124#[must_use = "search options do nothing until passed to a search"]
125pub struct SearchOptions {
126    /// Neighbours to return.
127    pub final_num_neighbors: Option<usize>,
128    /// Candidates kept for reordering (Python: `pre_reorder_num_neighbors`).
129    pub pre_reorder_num_neighbors: Option<usize>,
130    /// Partitions to search (Python: `leaves_to_search`).
131    pub leaves_to_search: Option<usize>,
132}
133
134impl SearchOptions {
135    /// Return `k` neighbours, everything else from the config.
136    pub fn k(k: usize) -> Self {
137        SearchOptions { final_num_neighbors: Some(k), ..Default::default() }
138    }
139    pub fn pre_reorder_num_neighbors(mut self, n: usize) -> Self {
140        self.pre_reorder_num_neighbors = Some(n);
141        self
142    }
143    pub fn leaves_to_search(mut self, n: usize) -> Self {
144        self.leaves_to_search = Some(n);
145        self
146    }
147
148    fn ffi(&self) -> Result<(i32, i32, i32)> {
149        Ok((
150            opt_i32(self.final_num_neighbors, "final_num_neighbors")?,
151            opt_i32(self.pre_reorder_num_neighbors, "pre_reorder_num_neighbors")?,
152            opt_i32(self.leaves_to_search, "leaves_to_search")?,
153        ))
154    }
155}
156
157// ---------------------------------------------------------------------------
158// ScannIndex
159// ---------------------------------------------------------------------------
160
161/// A built ScaNN index (`research_scann::ScannInterface`).
162///
163/// Searching takes `&self` and may run concurrently from several threads;
164/// everything that changes the index takes `&mut self`.
165pub struct ScannIndex {
166    inner: cxx::UniquePtr<ffi::ScannIndex>,
167    /// Serializes `health_stats`: see the SAFETY note below.
168    health_stats_lock: Mutex<()>,
169}
170
171// SAFETY: ScannInterface has no thread affinity. What &self reaches:
172// search (ScaNN serves concurrent queries on one searcher by design, and
173// the Python binding releases the GIL around them), size and
174// dimensionality (plain reads), and health_stats. The last is a const
175// member function in C++, but it recomputes cached imbalance figures in a
176// `mutable` HealthStatsCollector, so two concurrent calls would race;
177// health_stats_lock serializes them (searches don't touch the collector).
178// All mutation goes through &mut self, so Rust's aliasing rules keep it
179// exclusive.
180unsafe impl Send for ScannIndex {}
181unsafe impl Sync for ScannIndex {}
182
183impl fmt::Debug for ScannIndex {
184    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
185        f.debug_struct("ScannIndex")
186            .field("len", &self.len())
187            .field("dimensionality", &self.dimensionality())
188            .finish()
189    }
190}
191
192impl ScannIndex {
193    fn wrap(inner: cxx::UniquePtr<ffi::ScannIndex>) -> Self {
194        ScannIndex { inner, health_stats_lock: Mutex::new(()) }
195    }
196
197    /// Builds an index over `dataset` (row-major, `n x dimensionality`)
198    /// with a text-format ScaNN config, e.g. from [`ConfigBuilder::build`].
199    pub fn new(dataset: &[f32], dimensionality: usize, config: &str) -> Result<Self> {
200        Self::with_training_threads(dataset, dimensionality, config, 0)
201    }
202
203    /// Like [`new`](Self::new), training with `training_threads` threads
204    /// (0: the CPUs the process may use, see [`set_num_threads`](Self::set_num_threads)).
205    pub fn with_training_threads(
206        dataset: &[f32],
207        dimensionality: usize,
208        config: &str,
209        training_threads: usize,
210    ) -> Result<Self> {
211        let n = rows(dataset, dimensionality, "dataset")?;
212        if n == 0 {
213            return invalid("dataset is empty");
214        }
215        if u32::try_from(n).is_err() {
216            return invalid(format!("{n} datapoints exceed the 32-bit index space"));
217        }
218        let threads = to_i32(training_threads, "training_threads")?;
219        Ok(ScannIndex::wrap(ffi::scann_new(dataset, n as u64, config, threads)?))
220    }
221
222    /// Loads an index written by [`serialize`](Self::serialize) -- or by
223    /// Python's `searcher.serialize(dir)`; the on-disk format is the same.
224    pub fn load(dir: impl AsRef<Path>) -> Result<Self> {
225        let dir = path_str(dir.as_ref())?;
226        Ok(ScannIndex::wrap(ffi::scann_load(dir)?))
227    }
228
229    /// Writes the index to `dir` (which must exist), readable by
230    /// [`load`](Self::load) and by Python's `scann_ops_pybind.load_searcher`.
231    /// `relative_path` records asset paths relative to `dir`, so the
232    /// directory can be moved.
233    ///
234    /// An index already in `dir` is replaced: the files are staged, then
235    /// renamed into place with the manifest last, so an interrupted
236    /// `serialize` leaves the old index, the new one, or a directory that
237    /// [`load`](Self::load) rejects, never a mix of both. Index files the
238    /// new index doesn't have (including a Python `scann_docids.pkl`) are
239    /// removed.
240    pub fn serialize(&mut self, dir: impl AsRef<Path>, relative_path: bool) -> Result<()> {
241        let dir = path_str(dir.as_ref())?;
242        Ok(ffi::scann_serialize(self.inner.pin_mut(), dir, relative_path)?)
243    }
244
245    /// Nearest neighbours of one query.
246    pub fn search(&self, query: &[f32], options: SearchOptions) -> Result<Neighbors> {
247        self.check_query(query.len())?;
248        let (k, pre, leaves) = options.ffi()?;
249        Ok(ffi::scann_search(&self.inner, query, k, pre, leaves)?)
250    }
251
252    /// Nearest neighbours of each row of `queries` (row-major,
253    /// `n x dimensionality`), searched as one batch.
254    pub fn search_batched(&self, queries: &[f32], options: SearchOptions) -> Result<Vec<Neighbors>> {
255        self.batched(queries, options, false, 256)
256    }
257
258    /// Like [`search_batched`](Self::search_batched), splitting the batch
259    /// into chunks of at most `batch_size` queries searched on the index's
260    /// thread pool (see [`set_num_threads`](Self::set_num_threads)).
261    pub fn search_batched_parallel(
262        &self,
263        queries: &[f32],
264        options: SearchOptions,
265        batch_size: usize,
266    ) -> Result<Vec<Neighbors>> {
267        if batch_size == 0 {
268            return invalid("batch_size must be > 0");
269        }
270        self.batched(queries, options, true, batch_size)
271    }
272
273    fn batched(
274        &self,
275        queries: &[f32],
276        options: SearchOptions,
277        parallel: bool,
278        batch_size: usize,
279    ) -> Result<Vec<Neighbors>> {
280        let n = rows(queries, self.dimensionality(), "queries")?;
281        let (k, pre, leaves) = options.ffi()?;
282        let bs = to_i32(batch_size, "batch_size")?;
283        Ok(ffi::scann_search_batched(&self.inner, queries, n as u64, k, pre, leaves, parallel, bs)?)
284    }
285
286    fn check_query(&self, len: usize) -> Result<()> {
287        let dim = self.dimensionality();
288        if len != dim {
289            return invalid(format!("query has {len} dimensions, the index has {dim}"));
290        }
291        Ok(())
292    }
293
294    /// Number of datapoints in the index.
295    pub fn len(&self) -> usize {
296        ffi::scann_size(&self.inner) as usize
297    }
298
299    pub fn is_empty(&self) -> bool {
300        self.len() == 0
301    }
302
303    pub fn dimensionality(&self) -> usize {
304        ffi::scann_dimensionality(&self.inner) as usize
305    }
306
307    /// The config the index currently runs with, as ScaNN text format.
308    pub fn config(&mut self) -> String {
309        ffi::scann_config(self.inner.pin_mut())
310    }
311
312    /// Sets how many threads
313    /// [`search_batched_parallel`](Self::search_batched_parallel) and
314    /// mutations use, the calling thread included: the index starts
315    /// `num_threads - 1` pool threads, on first use. 0 or 1: no pool
316    /// (everything runs on the calling thread). The default is the number of
317    /// CPUs the process may use (affinity mask and cgroup CPU quota), or
318    /// `SCANN_NUM_THREADS` if set. (Before 0.2.1, `num_threads` pool threads
319    /// were started, so n + 1 threads searched.)
320    pub fn set_num_threads(&mut self, num_threads: usize) -> Result<()> {
321        let n = to_i32(num_threads, "num_threads")?;
322        ffi::scann_set_num_threads(self.inner.pin_mut(), n);
323        Ok(())
324    }
325
326    /// Reserves space for `n_points` datapoints in total.
327    pub fn reserve(&mut self, n_points: usize) -> Result<()> {
328        Ok(ffi::scann_reserve(self.inner.pin_mut(), n_points as u64)?)
329    }
330
331    /// Adds the rows of `vectors`; returns their indices.
332    pub fn add(&mut self, vectors: &[f32]) -> Result<Vec<u32>> {
333        let n = rows(vectors, self.dimensionality(), "vectors")?;
334        self.upsert(&vec![None; n], vectors, 1)
335    }
336
337    /// For each row of `vectors`: replaces datapoint `ids[i]`, or adds a new
338    /// one if `ids[i]` is `None`. Rows are processed `batch_size` at a time
339    /// (> 1 parallelizes on the thread pool); the index's incremental
340    /// maintenance (which may retrain it) runs once, after all of them.
341    /// Returns each row's index.
342    ///
343    /// Python's `searcher.upsert` maps docids to these indices on top.
344    ///
345    /// An index listed more than once is rejected before anything changes,
346    /// as in [`delete`](Self::delete) (and Python's `upsert` with a repeated
347    /// docid).
348    pub fn upsert(&mut self, ids: &[Option<u32>], vectors: &[f32], batch_size: usize) -> Result<Vec<u32>> {
349        let n = rows(vectors, self.dimensionality(), "vectors")?;
350        if n != ids.len() {
351            return invalid(format!("{} ids for {n} vectors", ids.len()));
352        }
353        if batch_size == 0 {
354            return invalid("batch_size must be > 0");
355        }
356        let mut seen = HashSet::new();
357        if let Some(dup) = ids.iter().flatten().find(|&&id| !seen.insert(id)) {
358            return invalid(format!("upsert: index {dup} listed more than once"));
359        }
360        let ids: Vec<i64> = ids.iter().map(|id| id.map_or(-1, i64::from)).collect();
361        let bs = to_i32(batch_size, "batch_size")?;
362        Ok(ffi::scann_upsert(self.inner.pin_mut(), &ids, vectors, bs)?)
363    }
364
365    /// Deletes the datapoints at `ids`, each an index as it is before the
366    /// call. As in ScaNN, the last datapoint moves into each freed slot, so
367    /// some remaining datapoints change index: the result lists each of
368    /// them as `(old index, new index)`, sorted by old index.
369    ///
370    /// Duplicate or out-of-range ids are rejected before anything changes.
371    pub fn delete(&mut self, ids: &[u32]) -> Result<Vec<(u32, u32)>> {
372        let len = self.len();
373        if let Some(&bad) = ids.iter().find(|&&id| id as usize >= len) {
374            return invalid(format!("delete: index {bad} out of range ({len} points)"));
375        }
376        // Highest first: the datapoint that fills a freed slot then always
377        // comes from above every remaining id, so each id still refers to
378        // the datapoint it named before the call.
379        let mut order = ids.to_vec();
380        order.sort_unstable_by(|a, b| b.cmp(a));
381        if let Some(w) = order.windows(2).find(|w| w[0] == w[1]) {
382            return invalid(format!("delete: index {} listed more than once", w[0]));
383        }
384        ffi::scann_delete(self.inner.pin_mut(), &order)?;
385
386        // Replay the moves: current position -> original index, for the
387        // datapoints that moved.
388        let mut origin: HashMap<u32, u32> = HashMap::new();
389        let mut remaining = len as u32;
390        for &id in &order {
391            let last = remaining - 1;
392            let moved = origin.remove(&last).unwrap_or(last);
393            origin.remove(&id);
394            if id != last {
395                origin.insert(id, moved);
396            }
397            remaining -= 1;
398        }
399        let mut moves: Vec<(u32, u32)> = origin.into_iter().map(|(now, was)| (was, now)).collect();
400        moves.sort_unstable();
401        Ok(moves)
402    }
403
404    /// Retrains the partitioning and quantization on the current data, with
405    /// `config` (text format) or, if `None`, the current config.
406    pub fn rebalance(&mut self, config: Option<&str>) -> Result<()> {
407        Ok(ffi::scann_rebalance(self.inner.pin_mut(), config.unwrap_or(""))?)
408    }
409
410    /// Partition balance and quantization error, as tracked by scann-core.
411    ///
412    /// `avg_quantization_error` is NaN when it can't be known: a tree without
413    /// float reordering drops its float data once the index is created (built,
414    /// loaded, rebalanced), so after an upsert or delete (or
415    /// [`initialize_health_stats`](Self::initialize_health_stats)) it is NaN
416    /// until the next [`rebalance`](Self::rebalance), and AH without
417    /// reordering saves no float data (NaN after loading). NaN != NaN, so
418    /// compare two `HealthStats` field by field. For a tree with a
419    /// PCA/TRUNCATE projection it is measured in the projected space.
420    pub fn health_stats(&self) -> Result<HealthStats> {
421        let _guard = self.health_stats_lock.lock().unwrap_or_else(|e| e.into_inner());
422        Ok(ffi::scann_health_stats(&self.inner)?)
423    }
424
425    /// Recomputes the statistics behind [`health_stats`](Self::health_stats)
426    /// from scratch.
427    pub fn initialize_health_stats(&mut self) -> Result<()> {
428        Ok(ffi::scann_initialize_health_stats(self.inner.pin_mut())?)
429    }
430}
431
432fn path_str(p: &Path) -> Result<&str> {
433    p.to_str()
434        .ok_or_else(|| ScannError::InvalidArgument(format!("path {p:?} is not valid UTF-8")))
435}
436
437// ---------------------------------------------------------------------------
438// ConfigBuilder
439// ---------------------------------------------------------------------------
440
441#[derive(Debug, Clone, Copy, PartialEq, Eq)]
442pub enum DistanceMeasure {
443    DotProduct,
444    SquaredL2,
445}
446
447/// How vectors are stored for scoring (Python: `scann.ReorderType`).
448#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
449pub enum Quantization {
450    #[default]
451    Float32,
452    Int8,
453    Bfloat16,
454}
455
456#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
457pub enum HashType {
458    #[default]
459    Lut16,
460    Lut256,
461}
462
463/// Python: `scann_builder.IncrementalMode`.
464#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
465pub enum IncrementalMode {
466    #[default]
467    None,
468    Online,
469    OnlineIncremental,
470}
471
472/// Which rules [`ConfigBuilder::autopilot_with`] chooses the configuration
473/// with (Python: `autopilot(rules=...)`).
474#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
475pub enum AutopilotRules {
476    /// scann-core's rules, from its tuning study (docs/tuning.md, "Defaults
477    /// and autopilot").
478    #[default]
479    Tuned,
480    /// Upstream ScaNN's rules, as scann-core 0.2.0 used.
481    Upstream,
482}
483
484/// Options for [`ConfigBuilder::autopilot_with`] (Python: `autopilot()`).
485#[derive(Debug, Clone, Copy, PartialEq, Eq)]
486pub struct AutopilotOptions {
487    pub mode: IncrementalMode,
488    /// The reordering data's precision (default float32).
489    pub quantize: Quantization,
490    pub rules: AutopilotRules,
491    /// Tuned rules with [`DistanceMeasure::SquaredL2`]: whether the index may
492    /// be built as [`l2_as_dot_product`](ConfigBuilder::l2_as_dot_product),
493    /// which the rules choose when the data suits it.
494    pub allow_l2_as_dot_product: bool,
495}
496
497impl Default for AutopilotOptions {
498    fn default() -> Self {
499        AutopilotOptions {
500            mode: IncrementalMode::None,
501            quantize: Quantization::Float32,
502            rules: AutopilotRules::Tuned,
503            allow_l2_as_dot_product: true,
504        }
505    }
506}
507
508impl AutopilotOptions {
509    pub fn new() -> Self {
510        Self::default()
511    }
512    pub fn mode(mut self, mode: IncrementalMode) -> Self {
513        self.mode = mode;
514        self
515    }
516    pub fn quantize(mut self, quantize: Quantization) -> Self {
517        self.quantize = quantize;
518        self
519    }
520    pub fn rules(mut self, rules: AutopilotRules) -> Self {
521        self.rules = rules;
522        self
523    }
524    pub fn allow_l2_as_dot_product(mut self, allow: bool) -> Self {
525        self.allow_l2_as_dot_product = allow;
526        self
527    }
528}
529
530/// When a partition has grown enough to be retrained in place (Python's
531/// `incremental_threshold`: an int is a point count, a float a fraction).
532#[derive(Debug, Clone, Copy, PartialEq)]
533pub enum IncrementalThreshold {
534    Points(u64),
535    Fraction(f64),
536}
537
538fn q(q: Quantization) -> ffi::Quantization {
539    match q {
540        Quantization::Float32 => ffi::Quantization::Float32,
541        Quantization::Int8 => ffi::Quantization::Int8,
542        Quantization::Bfloat16 => ffi::Quantization::Bfloat16,
543    }
544}
545
546fn nan_if_none(v: Option<f64>) -> f64 {
547    v.unwrap_or(f64::NAN)
548}
549
550/// Python: `ScannBuilder.tree()`. Defaults match Python's.
551#[derive(Debug, Clone, PartialEq)]
552#[must_use = "options do nothing until passed to ConfigBuilder"]
553pub struct TreeOptions {
554    pub num_leaves: u32,
555    pub num_leaves_to_search: u32,
556    pub training_sample_size: u64,
557    pub min_partition_size: u32,
558    pub training_iterations: u32,
559    pub spherical: bool,
560    pub quantize_centroids: bool,
561    /// Random center initialization (Python's default). Upstream's random
562    /// initialization depends on hash-table iteration order, so training
563    /// isn't reproducible run to run; `false` (k-means++) is.
564    pub random_init: bool,
565    pub incremental_threshold: Option<IncrementalThreshold>,
566    /// Anisotropic vector quantization of the centers (dot product only).
567    pub avq: Option<f64>,
568    /// SOAR spilling (dot product only).
569    pub soar_lambda: Option<f64>,
570    pub overretrieve_factor: Option<f64>,
571}
572
573impl TreeOptions {
574    pub fn new(num_leaves: u32, num_leaves_to_search: u32) -> Self {
575        TreeOptions {
576            num_leaves,
577            num_leaves_to_search,
578            training_sample_size: 100_000,
579            min_partition_size: 50,
580            training_iterations: 12,
581            spherical: false,
582            quantize_centroids: false,
583            random_init: true,
584            incremental_threshold: None,
585            avq: None,
586            soar_lambda: None,
587            overretrieve_factor: None,
588        }
589    }
590    pub fn training_sample_size(mut self, n: u64) -> Self {
591        self.training_sample_size = n;
592        self
593    }
594    pub fn min_partition_size(mut self, n: u32) -> Self {
595        self.min_partition_size = n;
596        self
597    }
598    pub fn training_iterations(mut self, n: u32) -> Self {
599        self.training_iterations = n;
600        self
601    }
602    /// Spherical k-means. The index then stores unit vectors: rows are
603    /// L2-normalized at build time and on upsert.
604    pub fn spherical(mut self, v: bool) -> Self {
605        self.spherical = v;
606        self
607    }
608    pub fn quantize_centroids(mut self, v: bool) -> Self {
609        self.quantize_centroids = v;
610        self
611    }
612    pub fn random_init(mut self, v: bool) -> Self {
613        self.random_init = v;
614        self
615    }
616    pub fn incremental_threshold(mut self, t: IncrementalThreshold) -> Self {
617        self.incremental_threshold = Some(t);
618        self
619    }
620    pub fn avq(mut self, eta: f64) -> Self {
621        self.avq = Some(eta);
622        self
623    }
624    pub fn soar_lambda(mut self, lambda: f64) -> Self {
625        self.soar_lambda = Some(lambda);
626        self
627    }
628    pub fn overretrieve_factor(mut self, f: f64) -> Self {
629        self.overretrieve_factor = Some(f);
630        self
631    }
632
633    fn ffi(&self) -> Result<ffi::FfiTreeOptions> {
634        let (points, fraction) = match self.incremental_threshold {
635            None => (-1, f64::NAN),
636            Some(IncrementalThreshold::Points(p)) => {
637                (i64::try_from(p).or_else(|_| invalid("incremental_threshold too large"))?, f64::NAN)
638            }
639            Some(IncrementalThreshold::Fraction(f)) => (-1, f),
640        };
641        Ok(ffi::FfiTreeOptions {
642            num_leaves: to_i32(self.num_leaves as usize, "num_leaves")?,
643            num_leaves_to_search: to_i32(self.num_leaves_to_search as usize, "num_leaves_to_search")?,
644            training_sample_size: i64::try_from(self.training_sample_size)
645                .or_else(|_| invalid("training_sample_size too large"))?,
646            min_partition_size: to_i32(self.min_partition_size as usize, "min_partition_size")?,
647            training_iterations: to_i32(self.training_iterations as usize, "training_iterations")?,
648            spherical: self.spherical,
649            quantize_centroids: self.quantize_centroids,
650            random_init: self.random_init,
651            incremental_threshold_points: points,
652            incremental_threshold_fraction: fraction,
653            avq: nan_if_none(self.avq),
654            soar_lambda: nan_if_none(self.soar_lambda),
655            overretrieve_factor: nan_if_none(self.overretrieve_factor),
656        })
657    }
658}
659
660/// Python: `ScannBuilder.upper_tree()`: a second partitioning level above
661/// the tree. Requires [`ConfigBuilder::tree`].
662#[derive(Debug, Clone, PartialEq)]
663#[must_use = "options do nothing until passed to ConfigBuilder"]
664pub struct UpperTreeOptions {
665    pub num_leaves: u32,
666    pub num_leaves_to_search: u32,
667    pub avq: Option<f64>,
668    pub soar_lambda: Option<f64>,
669    pub overretrieve_factor: Option<f64>,
670    pub scoring_mode: Quantization,
671    pub anisotropic_quantization_threshold: Option<f64>,
672}
673
674impl UpperTreeOptions {
675    pub fn new(num_leaves: u32, num_leaves_to_search: u32) -> Self {
676        UpperTreeOptions {
677            num_leaves,
678            num_leaves_to_search,
679            avq: None,
680            soar_lambda: None,
681            overretrieve_factor: None,
682            scoring_mode: Quantization::Int8,
683            anisotropic_quantization_threshold: None,
684        }
685    }
686    pub fn avq(mut self, eta: f64) -> Self {
687        self.avq = Some(eta);
688        self
689    }
690    pub fn soar_lambda(mut self, lambda: f64) -> Self {
691        self.soar_lambda = Some(lambda);
692        self
693    }
694    pub fn overretrieve_factor(mut self, f: f64) -> Self {
695        self.overretrieve_factor = Some(f);
696        self
697    }
698    pub fn scoring_mode(mut self, m: Quantization) -> Self {
699        self.scoring_mode = m;
700        self
701    }
702    pub fn anisotropic_quantization_threshold(mut self, t: f64) -> Self {
703        self.anisotropic_quantization_threshold = Some(t);
704        self
705    }
706
707    fn ffi(&self) -> Result<ffi::FfiUpperTreeOptions> {
708        Ok(ffi::FfiUpperTreeOptions {
709            num_leaves: to_i32(self.num_leaves as usize, "num_leaves")?,
710            num_leaves_to_search: to_i32(self.num_leaves_to_search as usize, "num_leaves_to_search")?,
711            avq: nan_if_none(self.avq),
712            soar_lambda: nan_if_none(self.soar_lambda),
713            overretrieve_factor: nan_if_none(self.overretrieve_factor),
714            scoring_mode: q(self.scoring_mode),
715            anisotropic_quantization_threshold: nan_if_none(self.anisotropic_quantization_threshold),
716        })
717    }
718}
719
720/// Python: `ScannBuilder.score_ah()`: asymmetric-hashing (product
721/// quantization) scoring.
722#[derive(Debug, Clone, PartialEq)]
723#[must_use = "options do nothing until passed to ConfigBuilder"]
724pub struct AhOptions {
725    pub dimensions_per_block: u32,
726    /// Anisotropic quantization (dot product); `None` = plain k-means PQ.
727    pub anisotropic_quantization_threshold: Option<f64>,
728    pub training_sample_size: u64,
729    pub hash_type: HashType,
730    pub training_iterations: u32,
731    /// `None`: on iff a tree is configured and the distance is dot product.
732    pub residual_quantization: Option<bool>,
733}
734
735impl AhOptions {
736    pub fn new(dimensions_per_block: u32) -> Self {
737        AhOptions {
738            dimensions_per_block,
739            anisotropic_quantization_threshold: None,
740            training_sample_size: 100_000,
741            hash_type: HashType::Lut16,
742            training_iterations: 10,
743            residual_quantization: None,
744        }
745    }
746    pub fn anisotropic_quantization_threshold(mut self, t: f64) -> Self {
747        self.anisotropic_quantization_threshold = Some(t);
748        self
749    }
750    pub fn training_sample_size(mut self, n: u64) -> Self {
751        self.training_sample_size = n;
752        self
753    }
754    pub fn hash_type(mut self, h: HashType) -> Self {
755        self.hash_type = h;
756        self
757    }
758    pub fn training_iterations(mut self, n: u32) -> Self {
759        self.training_iterations = n;
760        self
761    }
762    pub fn residual_quantization(mut self, v: bool) -> Self {
763        self.residual_quantization = Some(v);
764        self
765    }
766
767    fn ffi(&self) -> Result<ffi::FfiAhOptions> {
768        Ok(ffi::FfiAhOptions {
769            dimensions_per_block: to_i32(self.dimensions_per_block as usize, "dimensions_per_block")?,
770            anisotropic_quantization_threshold: nan_if_none(self.anisotropic_quantization_threshold),
771            training_sample_size: i64::try_from(self.training_sample_size)
772                .or_else(|_| invalid("training_sample_size too large"))?,
773            hash_type: match self.hash_type {
774                HashType::Lut16 => ffi::HashType::Lut16,
775                HashType::Lut256 => ffi::HashType::Lut256,
776            },
777            training_iterations: to_i32(self.training_iterations as usize, "training_iterations")?,
778            has_residual_quantization: self.residual_quantization.is_some(),
779            residual_quantization: self.residual_quantization.unwrap_or(false),
780        })
781    }
782}
783
784/// Python: `ScannBuilder.reorder()`: rescore the top candidates exactly (or
785/// with a finer quantization).
786#[derive(Debug, Clone, PartialEq)]
787#[must_use = "options do nothing until passed to ConfigBuilder"]
788pub struct ReorderOptions {
789    pub reordering_num_neighbors: u32,
790    pub quantize: Quantization,
791    pub anisotropic_quantization_threshold: Option<f64>,
792}
793
794impl ReorderOptions {
795    pub fn new(reordering_num_neighbors: u32) -> Self {
796        ReorderOptions {
797            reordering_num_neighbors,
798            quantize: Quantization::Float32,
799            anisotropic_quantization_threshold: None,
800        }
801    }
802    pub fn quantize(mut self, q: Quantization) -> Self {
803        self.quantize = q;
804        self
805    }
806    pub fn anisotropic_quantization_threshold(mut self, t: f64) -> Self {
807        self.anisotropic_quantization_threshold = Some(t);
808        self
809    }
810}
811
812/// Python: `ScannBuilder.l2_as_dot_product()`: squared L2 search through an
813/// inner-product index (the exact L2 -> MIPS reduction). The index stores
814/// each datapoint `x` as `[x, (center - |x|²) / (2 scale)]` and searches
815/// `[q, scale]` by dot product; results are squared L2 distances, and
816/// upserts, rebalancing and saved indexes keep `scale` and `center`. See
817/// [`ConfigBuilder::l2_as_dot_product`].
818#[derive(Debug, Clone, Copy, Default, PartialEq)]
819#[must_use = "options do nothing until passed to ConfigBuilder"]
820pub struct L2AsDotProductOptions {
821    /// The query's extra coordinate (> 0). `None`: 0.4 times the dataset's
822    /// RMS norm, `0.4 sqrt(mean |x|²)`.
823    pub scale: Option<f64>,
824    /// Any constant; it centres the datapoints' extra coordinate. `None`:
825    /// the dataset's mean `|x|²`.
826    pub center: Option<f64>,
827}
828
829impl L2AsDotProductOptions {
830    pub fn new() -> Self {
831        Self::default()
832    }
833    pub fn scale(mut self, s: f64) -> Self {
834        self.scale = Some(s);
835        self
836    }
837    pub fn center(mut self, c: f64) -> Self {
838        self.center = Some(c);
839        self
840    }
841}
842
843/// Python: `ScannBuilder.pca()`. Set at most one of `reduction_dim` and
844/// `pca_significance_threshold`; with neither, the threshold is 0.8.
845#[derive(Debug, Clone, PartialEq)]
846#[must_use = "options do nothing until passed to ConfigBuilder"]
847pub struct PcaOptions {
848    pub reduction_dim: Option<u32>,
849    pub pca_significance_threshold: Option<f64>,
850    pub pca_truncation_threshold: f64,
851}
852
853impl Default for PcaOptions {
854    fn default() -> Self {
855        PcaOptions { reduction_dim: None, pca_significance_threshold: None, pca_truncation_threshold: 0.6 }
856    }
857}
858
859impl PcaOptions {
860    pub fn reduction_dim(dim: u32) -> Self {
861        PcaOptions { reduction_dim: Some(dim), ..Default::default() }
862    }
863    pub fn significance_threshold(t: f64) -> Self {
864        PcaOptions { pca_significance_threshold: Some(t), ..Default::default() }
865    }
866}
867
868/// Builds a ScaNN config from high-level options, like Python's
869/// `scann_ops_pybind.builder(db, num_neighbors, distance_measure)`.
870///
871/// Where Python silently ignores an option (an upper tree or PCA without a
872/// tree, autopilot combined with manual options, an option set twice, ...)
873/// [`build`](Self::build) returns an error instead.
874#[must_use = "a ConfigBuilder does nothing until build() or build_index() is called"]
875pub struct ConfigBuilder {
876    inner: cxx::UniquePtr<ffi::ConfigBuilder>,
877    dimensionality: usize,
878    training_threads: usize,
879    error: Option<ScannError>,
880}
881
882impl fmt::Debug for ConfigBuilder {
883    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
884        f.debug_struct("ConfigBuilder").field("dimensionality", &self.dimensionality).finish()
885    }
886}
887
888impl ConfigBuilder {
889    pub fn new(num_neighbors: usize, distance: DistanceMeasure, dimensionality: usize) -> Self {
890        let mut error = None;
891        let k = to_i32(num_neighbors, "num_neighbors").unwrap_or_else(|e| {
892            error = Some(e);
893            0
894        });
895        let dim = u32::try_from(dimensionality).unwrap_or_else(|_| {
896            error = Some(ScannError::InvalidArgument("dimensionality too large".into()));
897            0
898        });
899        let d = match distance {
900            DistanceMeasure::DotProduct => ffi::DistanceMeasure::DotProduct,
901            DistanceMeasure::SquaredL2 => ffi::DistanceMeasure::SquaredL2,
902        };
903        ConfigBuilder {
904            inner: ffi::config_builder_new(k, d, dim),
905            dimensionality,
906            training_threads: 0,
907            error,
908        }
909    }
910
911    // Conversion errors are deferred to build(), like the C++ builder's own
912    // validation, so the chain stays infallible.
913    fn apply<T>(mut self, v: Result<T>, f: impl FnOnce(std::pin::Pin<&mut ffi::ConfigBuilder>, &T)) -> Self {
914        match v {
915            Ok(v) => f(self.inner.pin_mut(), &v),
916            Err(e) => {
917                self.error.get_or_insert(e);
918            }
919        }
920        self
921    }
922
923    /// Partition the dataset with a k-means tree.
924    pub fn tree(self, o: TreeOptions) -> Self {
925        let v = o.ffi();
926        self.apply(v, ffi::config_builder_tree)
927    }
928
929    /// Add a second partitioning level above the tree.
930    pub fn upper_tree(self, o: UpperTreeOptions) -> Self {
931        let v = o.ffi();
932        self.apply(v, ffi::config_builder_upper_tree)
933    }
934
935    /// Score with asymmetric hashing.
936    pub fn score_ah(self, o: AhOptions) -> Self {
937        let v = o.ffi();
938        self.apply(v, ffi::config_builder_score_ah)
939    }
940
941    /// Score exactly (optionally on quantized vectors).
942    pub fn score_brute_force(self, quantize: Quantization) -> Self {
943        self.apply(Ok(q(quantize)), |b, &qq| ffi::config_builder_score_brute_force(b, qq))
944    }
945
946    pub fn reorder(self, o: ReorderOptions) -> Self {
947        let v = to_i32(o.reordering_num_neighbors as usize, "reordering_num_neighbors").map(|k| {
948            ffi::FfiReorderOptions {
949                reordering_num_neighbors: k,
950                quantize: q(o.quantize),
951                anisotropic_quantization_threshold: nan_if_none(o.anisotropic_quantization_threshold),
952            }
953        });
954        self.apply(v, ffi::config_builder_reorder)
955    }
956
957    /// Project with PCA before partitioning (requires a tree).
958    pub fn pca(self, o: PcaOptions) -> Self {
959        let v = match o.reduction_dim {
960            None => Ok(-1),
961            Some(d) => to_i32(d as usize, "reduction_dim"),
962        }
963        .map(|d| ffi::FfiPcaOptions {
964            reduction_dim: d,
965            pca_significance_threshold: nan_if_none(o.pca_significance_threshold),
966            pca_truncation_threshold: o.pca_truncation_threshold,
967        });
968        self.apply(v, ffi::config_builder_pca)
969    }
970
971    /// Keep only the first `reduction_dim` dimensions (requires a tree).
972    pub fn truncate(self, reduction_dim: usize) -> Self {
973        let v = to_i32(reduction_dim, "reduction_dim");
974        self.apply(v, |b, &d| ffi::config_builder_truncate(b, d))
975    }
976
977    /// Let scann-core pick the configuration for the data, with the tuned
978    /// rules and the given reordering precision:
979    /// `autopilot_with(AutopilotOptions::new().mode(mode).quantize(quantize))`.
980    /// Can't be combined with manual options.
981    pub fn autopilot(self, mode: IncrementalMode, quantize: Quantization) -> Self {
982        self.autopilot_with(AutopilotOptions::new().mode(mode).quantize(quantize))
983    }
984
985    /// Let scann-core pick the configuration for the data (Python:
986    /// `autopilot(mode, quantize, rules, allow_l2_as_dot_product)`). Can't
987    /// be combined with manual options.
988    pub fn autopilot_with(self, o: AutopilotOptions) -> Self {
989        let m = match o.mode {
990            IncrementalMode::None => ffi::IncrementalMode::None,
991            IncrementalMode::Online => ffi::IncrementalMode::Online,
992            IncrementalMode::OnlineIncremental => ffi::IncrementalMode::OnlineIncremental,
993        };
994        let v = ffi::FfiAutopilotOptions {
995            mode: m,
996            quantize: q(o.quantize),
997            upstream_rules: o.rules == AutopilotRules::Upstream,
998            allow_l2_as_dot_product: o.allow_l2_as_dot_product,
999        };
1000        self.apply(Ok(v), ffi::config_builder_autopilot)
1001    }
1002
1003    /// Squared L2 search through an inner-product index (the exact L2 ->
1004    /// MIPS reduction; requires [`DistanceMeasure::SquaredL2`]). The other
1005    /// options then describe a dot-product index over `dimensionality + 1`
1006    /// dimensions: [`TreeOptions::avq`], [`TreeOptions::soar_lambda`],
1007    /// anisotropic AH and residual quantization apply, and AH blocks cover
1008    /// the extra coordinate. Not combinable with a spherical tree,
1009    /// [`truncate`](Self::truncate) or [`autopilot`](Self::autopilot).
1010    pub fn l2_as_dot_product(self, o: L2AsDotProductOptions) -> Self {
1011        let v = match (o.scale, o.center) {
1012            (Some(s), _) if !(s.is_finite() && s > 0.0) => {
1013                invalid(format!("l2_as_dot_product: scale must be positive and finite, not {s}"))
1014            }
1015            (_, Some(c)) if !c.is_finite() => {
1016                invalid(format!("l2_as_dot_product: center must be finite, not {c}"))
1017            }
1018            (s, c) => Ok((nan_if_none(s), nan_if_none(c))),
1019        };
1020        self.apply(v, |b, &(s, c)| ffi::config_builder_l2_as_dot_product(b, s, c))
1021    }
1022
1023    /// Training threads for [`build_index`](Self::build_index) (0: default).
1024    pub fn training_threads(mut self, n: usize) -> Self {
1025        self.training_threads = n;
1026        self
1027    }
1028
1029    /// The config as ScaNN text format. `num_points` only matters with
1030    /// [`autopilot`](Self::autopilot), which sizes the config to the data.
1031    /// Its tuned rules also look at the data when the index is built:
1032    /// without it, this config assumes unit norms (for the anisotropic
1033    /// threshold), and a squared L2 one leaves out the `l2_as_dot_product`
1034    /// the build may choose. [`ScannIndex::config`] shows what was built.
1035    pub fn build(&self, num_points: u64) -> Result<String> {
1036        if let Some(e) = &self.error {
1037            return Err(e.clone());
1038        }
1039        Ok(ffi::config_builder_build(&self.inner, num_points)?)
1040    }
1041
1042    /// Builds the config for `dataset` and an index over it.
1043    pub fn build_index(&self, dataset: &[f32]) -> Result<ScannIndex> {
1044        let n = rows(dataset, self.dimensionality, "dataset")?;
1045        let config = self.build(n as u64)?;
1046        ScannIndex::with_training_threads(dataset, self.dimensionality, &config, self.training_threads)
1047    }
1048}