cognitum-one 0.2.1

Official Cognitum SDK for Rust
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

//! Vector store request / response shapes.
//!
//! Phase 1 wraps `/api/v1/store/status`, `/query`, `/ingest`.

use serde::{Deserialize, Serialize};

use super::Extras;

/// `GET /api/v1/store/status` response shape.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct StoreStatus {
    /// Total vectors in the store.
    #[serde(default)]
    pub total_vectors: u64,
    /// Tombstoned vectors awaiting compaction.
    #[serde(default)]
    pub deleted_vectors: u64,
    /// On-disk size of the vector file.
    #[serde(default)]
    pub file_size_bytes: u64,
    /// Vector dimension.
    #[serde(default)]
    pub dimension: u32,
    #[serde(flatten)]
    pub extras: Extras,
}

/// `POST /api/v1/store/query` request body.
///
/// Per swarm finding: the field is **`vector`**, not `query`.
#[derive(Debug, Clone, Serialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct StoreQuery {
    /// The query vector. Length MUST equal the store's `dimension`.
    pub vector: Vec<f32>,
    /// Number of neighbors to return.
    pub k: u32,
}

/// `POST /api/v1/store/query` response body.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct StoreQueryResult {
    /// Nearest-neighbor hits ordered by `distance` ascending.
    #[serde(default)]
    pub results: Vec<StoreQueryHit>,
    /// Wall-clock ms the seed spent on the query.
    #[serde(default)]
    pub query_ms: f64,
    #[serde(flatten)]
    pub extras: Extras,
}

/// A single nearest-neighbor hit.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct StoreQueryHit {
    /// Content-hashed 64-bit ID.
    #[serde(default)]
    pub id: u64,
    /// Distance (squared L2 or cosine depending on store config).
    #[serde(default)]
    pub distance: f32,
    /// Opaque metadata blob per-vector.
    #[serde(default)]
    pub metadata: serde_json::Value,
    #[serde(flatten)]
    pub extras: Extras,
}

/// One entry in a `POST /api/v1/store/ingest` batch.
#[derive(Debug, Clone, Serialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct StoreIngestEntry {
    /// Caller-supplied ID (will be rehashed server-side).
    pub id: String,
    /// Vector payload.
    pub values: Vec<f32>,
    /// Optional metadata blob.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub metadata: Option<serde_json::Value>,
}

/// `POST /api/v1/store/ingest` request body.
#[derive(Debug, Clone, Serialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct StoreIngest {
    /// Vectors to upsert.
    pub vectors: Vec<StoreIngestEntry>,
}

/// `POST /api/v1/store/ingest` response body.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct StoreIngestAck {
    /// Number of vectors accepted.
    #[serde(default)]
    pub ingested: u64,
    #[serde(flatten)]
    pub extras: Extras,
}