fornix 0.4.0

Knowledge storage, retrieval, and graph infrastructure for cognitive systems
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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

//! The `VectorAdapter` trait — the core interface for all vector backends.

use async_trait::async_trait;
use crate::common::namespace::Namespace;
use crate::common::pagination::{Page, PageParams};
use crate::store::health::HealthReport;
use crate::vector::{
    config::VectorConfig,
    error::Result,
    filter::MetadataFilter,
    result::{VectorRecord, VectorResult},
};

/// Options for a nearest-neighbour search.
#[derive(Debug, Clone)]
pub struct SearchOptions {
    /// Maximum number of results to return.
    pub limit: usize,
    /// Optional metadata filter applied to candidates before scoring.
    pub filter: Option<MetadataFilter>,
    /// Minimum similarity score; results below this threshold are excluded.
    pub min_similarity: Option<f32>,
    /// Whether to include the stored vector in each result.
    pub include_vectors: bool,
}

impl Default for SearchOptions {
    fn default() -> Self {
        Self {
            limit: 20,
            filter: None,
            min_similarity: None,
            include_vectors: false,
        }
    }
}

impl SearchOptions {
    pub fn with_limit(mut self, limit: usize) -> Self {
        self.limit = limit;
        self
    }

    pub fn with_filter(mut self, filter: MetadataFilter) -> Self {
        self.filter = Some(filter);
        self
    }

    pub fn with_min_similarity(mut self, min: f32) -> Self {
        self.min_similarity = Some(min);
        self
    }

    pub fn include_vectors(mut self) -> Self {
        self.include_vectors = true;
        self
    }
}

/// Options for a list operation.
#[derive(Debug, Clone)]
#[derive(Default)]
pub struct ListOptions {
    /// Optional metadata filter.
    pub filter: Option<MetadataFilter>,
    /// Whether to include the stored vector in each record.
    pub include_vectors: bool,
}


/// The core interface for all vector storage backends.
#[async_trait]
pub trait VectorAdapter: Send + Sync {
    /// The human-readable name of this adapter.
    fn name(&self) -> &'static str;

    /// Whether the adapter is currently connected.
    fn is_connected(&self) -> bool;

    /// The configuration this adapter was built from.
    fn config(&self) -> &VectorConfig;

    /// Insert or update a record. If a record with `id` already exists in
    /// `namespace`, its vector and metadata are replaced.
    async fn upsert(
        &self,
        id: &str,
        vector: Vec<f32>,
        metadata: Option<crate::common::metadata::Metadata>,
        namespace: Option<&Namespace>,
    ) -> Result<()>;

    /// Return the `limit` nearest neighbours to `query` in `namespace`,
    /// ordered by descending similarity.
    async fn nearest_neighbors(
        &self,
        query: &[f32],
        namespace: Option<&Namespace>,
        options: SearchOptions,
    ) -> Result<Vec<VectorResult>>;

    /// List records in `namespace` with optional filtering and pagination.
    async fn list(
        &self,
        namespace: Option<&Namespace>,
        page: PageParams,
        options: ListOptions,
    ) -> Result<Page<VectorRecord>>;

    /// Delete a single record. Returns `true` if it existed.
    async fn delete(&self, id: &str, namespace: Option<&Namespace>) -> Result<bool>;

    /// Delete all records in a namespace. Returns the number removed.
    async fn delete_namespace(&self, namespace: &Namespace) -> Result<usize>;

    /// Count records in `namespace`, or all records if `None`.
    async fn count(&self, namespace: Option<&Namespace>) -> Result<usize>;

    /// Health check for the backend connection.
    async fn healthcheck(&self) -> HealthReport;
}