weavatrix-search-vector 0.3.1

Persistent, mutable, bounded vector candidate search for Rust and Weavatrix
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

mod codec;
mod format;
mod io;
mod mutable_api;
mod reader;
mod validation;
mod writer;

use crate::error::SearchError;
use crate::mutable::MutableVectorIndex;
use crate::quantized::QuantizedIndex;
use std::path::Path;

/// Atomic persistence unit for mutable f32 state and an optional compact
/// representation.
#[derive(Debug)]
pub struct IndexBundle {
    mutable: MutableVectorIndex,
    quantized: Option<QuantizedIndex>,
}

impl IndexBundle {
    /// Creates a validated bundle.
    ///
    /// # Errors
    ///
    /// Returns an error when the compact representation does not describe the
    /// same active key set and configuration as the mutable index.
    pub fn new(
        mutable: MutableVectorIndex,
        quantized: Option<QuantizedIndex>,
    ) -> Result<Self, SearchError> {
        validation::validate_quantized(&mutable.snapshot(), quantized.as_ref())?;
        Ok(Self { mutable, quantized })
    }

    /// Returns the mutable f32 index and its delta/metadata state.
    #[must_use]
    pub const fn mutable(&self) -> &MutableVectorIndex {
        &self.mutable
    }

    /// Returns mutable access to the f32 index.
    ///
    /// Callers replacing active vectors must also replace or remove the
    /// compact representation before saving.
    #[must_use]
    pub const fn mutable_mut(&mut self) -> &mut MutableVectorIndex {
        &mut self.mutable
    }

    /// Returns the optional compact representation.
    #[must_use]
    pub const fn quantized(&self) -> Option<&QuantizedIndex> {
        self.quantized.as_ref()
    }

    /// Replaces the compact representation after validating bundle identity.
    ///
    /// # Errors
    ///
    /// Returns an error when config or active keys differ.
    pub fn set_quantized(&mut self, quantized: Option<QuantizedIndex>) -> Result<(), SearchError> {
        validation::validate_quantized(&self.mutable.snapshot(), quantized.as_ref())?;
        self.quantized = quantized;
        Ok(())
    }

    /// Consumes the bundle.
    #[must_use]
    pub fn into_parts(self) -> (MutableVectorIndex, Option<QuantizedIndex>) {
        (self.mutable, self.quantized)
    }

    /// Atomically saves vectors, graphs, mutation delta, metadata, and compact
    /// representation under one checksum.
    ///
    /// # Errors
    ///
    /// Returns a consistency, serialization, or filesystem error.
    pub fn save(&self, path: impl AsRef<Path>) -> Result<(), SearchError> {
        writer::save_complete(&self.mutable, self.quantized.as_ref(), path.as_ref())
    }

    /// Loads and validates a complete bundle.
    ///
    /// # Errors
    ///
    /// Returns a filesystem, integrity, format, or consistency error.
    pub fn load(path: impl AsRef<Path>) -> Result<Self, SearchError> {
        let (mutable, quantized) = reader::load_complete(path.as_ref())?;
        Self::new(mutable, quantized)
    }
}