warm-rust 0.6.5

Local-first search engine and agent memory: fast approximate nearest-neighbor and BM25 full-text search, encrypted stores, provable deletion, built on vector-symbolic architectures.
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

// Copyright 2024-2026 WritersLogic Contributors
// SPDX-License-Identifier: Apache-2.0

use super::WarmCore;
use crate::core::entangled::EntangledHVec;
use crate::core::types::RetrievalResult;
use anyhow::Result;

impl WarmCore {
    /// Encode a (head, relation, tail) triplet as `h XOR r XOR t` and memorize it.
    pub fn memorize_triplet(&self, id: String, h: String, r: String, t: String) -> Result<()> {
        super::mutation::validate_public_id(&id)?;
        if !self.meaning_enabled() {
            let triplet = self
                .try_encode_text(&h)?
                .bind(&self.try_encode_text(&r)?)
                .bind(&self.try_encode_text(&t)?);
            return self.memorize(id, triplet);
        }
        self.commit(&[super::mutation::Mutation::Triplet {
            id,
            subject: h,
            relation: r,
            object: t,
        }])
    }

    /// Encode an ordered sequence using position-based permutation and memorize it.
    pub fn memorize_sequence(&self, id: String, sequence: &[String]) -> Result<()> {
        if sequence.is_empty() {
            return Ok(());
        }
        self.memorize(id, self.encode_sequence(sequence)?)
    }

    /// Query for tails matching `head XOR relation`.
    pub fn query_triplet(&self, h: String, r: String, k: u32) -> Result<Vec<RetrievalResult>> {
        let vec_h = self.try_encode_text(&h)?;
        let vec_r = self.try_encode_text(&r)?;
        let query_vec = vec_h.bind(&vec_r);
        Ok(self.query(&query_vec, k))
    }

    /// Find analogy: A is to B as C is to ? Returns k closest matches.
    pub fn find_analogy(&self, a: &str, b: &str, c: &str, k: u32) -> Vec<RetrievalResult> {
        self.try_find_analogy(a, b, c, k).expect(
            "analogy encoding failed; use try_find_analogy to handle model or resource errors",
        )
    }

    pub fn try_find_analogy(
        &self,
        a: &str,
        b: &str,
        c: &str,
        k: u32,
    ) -> Result<Vec<RetrievalResult>> {
        let vec_a = self.try_encode_text(a)?;
        let vec_b = self.try_encode_text(b)?;
        let vec_c = self.try_encode_text(c)?;
        let target = vec_a.bind(&vec_b).bind(&vec_c);
        Ok(self.query(&target, k))
    }

    /// Query for sequences matching a partial sequence prefix.
    pub fn query_sequence(&self, partial: &[String], k: u32) -> Result<Vec<RetrievalResult>> {
        if partial.is_empty() {
            return Ok(vec![]);
        }
        Ok(self.query(&self.encode_sequence(partial)?, k))
    }

    /// Bundles `items`, each permuted by its position.
    fn encode_sequence(&self, items: &[String]) -> Result<EntangledHVec> {
        let texts: Vec<_> = items.iter().map(String::as_str).collect();
        let vecs: Vec<EntangledHVec> = self
            .try_encode_texts(&texts)?
            .into_iter()
            .enumerate()
            .map(|(i, vector)| vector.permute(i))
            .collect();
        Ok(self.bundle(&vecs))
    }
}