behest 0.3.0

A Rust-native cloud agent runtime with typed tools, pluggable memory, queues, and observability.
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

//! Provider-neutral embedding request and response types.

use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::provider::{ModelName, ProviderId, TokenUsage};

/// Request for vector embeddings.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct EmbeddingRequest {
    /// Provider-specific embedding model name.
    pub model: ModelName,
    /// Inputs to embed.
    pub input: Vec<EmbeddingInput>,
    /// Optional target embedding dimension.
    pub dimensions: Option<u32>,
    /// Application metadata forwarded to provider adapters.
    pub metadata: Value,
}

impl EmbeddingRequest {
    /// Creates an embedding request from explicit inputs.
    #[must_use]
    pub fn new(model: ModelName, input: Vec<EmbeddingInput>) -> Self {
        Self {
            model,
            input,
            dimensions: None,
            metadata: Value::Null,
        }
    }

    /// Creates an embedding request for one text input.
    #[must_use]
    pub fn from_text(model: ModelName, text: impl Into<String>) -> Self {
        Self::new(model, vec![EmbeddingInput::text(text)])
    }

    /// Sets the target embedding dimension.
    #[must_use]
    pub fn with_dimensions(mut self, dimensions: u32) -> Self {
        self.dimensions = Some(dimensions);
        self
    }

    /// Sets adapter metadata.
    #[must_use]
    pub fn with_metadata(mut self, metadata: Value) -> Self {
        self.metadata = metadata;
        self
    }
}

/// A single embedding input.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case", tag = "type")]
#[non_exhaustive]
pub enum EmbeddingInput {
    /// Plain text input.
    Text {
        /// Text to embed.
        text: String,
    },
    /// Tokenized input.
    Tokens {
        /// Provider-specific token IDs.
        tokens: Vec<u32>,
    },
}

impl EmbeddingInput {
    /// Creates a text embedding input.
    #[must_use]
    pub fn text(text: impl Into<String>) -> Self {
        Self::Text { text: text.into() }
    }

    /// Creates a token embedding input.
    #[must_use]
    pub fn tokens(tokens: Vec<u32>) -> Self {
        Self::Tokens { tokens }
    }
}

/// Response returned by an embedding provider.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct EmbeddingResponse {
    /// Provider that produced the embeddings.
    pub provider: ProviderId,
    /// Model that produced the embeddings.
    pub model: ModelName,
    /// Embeddings in the same order as request inputs.
    pub embeddings: Vec<Embedding>,
    /// Token accounting, when supplied by the provider.
    pub usage: Option<TokenUsage>,
    /// Raw provider response for adapters that retain it.
    pub raw: Option<Value>,
}

/// One embedding vector and its input index.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Embedding {
    /// Input index associated with this vector.
    pub index: usize,
    /// Dense embedding vector.
    pub vector: Vec<f32>,
}

impl Embedding {
    /// Creates one embedding vector.
    #[must_use]
    pub fn new(index: usize, vector: Vec<f32>) -> Self {
        Self { index, vector }
    }
}