serdes_ai_embeddings/
lib.rs

1//! # serdes-ai-embeddings
2//!
3//! Embedding models and vector operations for serdes-ai.
4//!
5//! This crate provides infrastructure for generating embeddings from text
6//! and performing vector similarity operations.
7//!
8//! ## Core Concepts
9//!
10//! - **[`EmbeddingModel`]**: Trait for embedding model implementations
11//! - **[`Embedding`]**: Vector representation with metadata
12//! - **[`Embedder`]**: High-level interface for embeddings
13//! - **Similarity functions**: Cosine, dot product, Euclidean distance
14//!
15//! ## Feature Flags
16//!
17//! - `openai` (default): OpenAI embedding models
18//! - `cohere`: Cohere embedding models
19//! - `voyage`: Voyage AI embeddings
20//! - `ollama`: Local Ollama embeddings
21//! - `full`: All providers
22//!
23//! ## Example
24//!
25//! ```ignore
26//! use serdes_ai_embeddings::{Embedder, EmbeddingModel};
27//!
28//! // Using the high-level interface
29//! let embedder = Embedder::from_env("openai:text-embedding-3-small")?;
30//!
31//! // Single embedding
32//! let result = embedder.embed_query("Hello, world!").await?;
33//! let embedding = result.embedding().unwrap();
34//!
35//! // Batch embeddings
36//! let result = embedder.embed_documents(vec![
37//!     "First document".into(),
38//!     "Second document".into(),
39//! ]).await?;
40//!
41//! // Similarity
42//! let similarity = result.embeddings[0].cosine_similarity(&result.embeddings[1]);
43//! ```
44//!
45//! ## Direct Model Usage
46//!
47//! ```ignore
48//! use serdes_ai_embeddings::OpenAIEmbeddingModel;
49//!
50//! let model = OpenAIEmbeddingModel::from_env("text-embedding-3-small")?;
51//! let result = model.embed_query("Hello!").await?;
52//! ```
53
54#![warn(missing_docs)]
55#![deny(unsafe_code)]
56#![cfg_attr(docsrs, feature(doc_cfg))]
57
58pub mod embedder;
59pub mod embedding;
60pub mod error;
61pub mod model;
62pub mod similarity;
63
64#[cfg(feature = "openai")]
65#[cfg_attr(docsrs, doc(cfg(feature = "openai")))]
66pub mod openai;
67
68#[cfg(feature = "cohere")]
69#[cfg_attr(docsrs, doc(cfg(feature = "cohere")))]
70pub mod cohere;
71
72// Re-exports
73pub use embedder::{infer_embedding_model, Embedder, EmbedderBuilder};
74pub use embedding::{Embedding, EmbeddingBatch};
75pub use error::{EmbeddingError, EmbeddingResult};
76pub use model::{
77    BoxedEmbeddingModel, EmbedInput, EmbeddingModel, EmbeddingOutput, EmbeddingSettings,
78    EncodingFormat, InputType, TruncationMode,
79};
80pub use similarity::{
81    angular_distance, centroid, cosine_similarity, dot_product, euclidean_distance,
82    manhattan_distance, normalize, pairwise_cosine, top_k_similar, weighted_average,
83};
84
85#[cfg(feature = "openai")]
86pub use openai::OpenAIEmbeddingModel;
87
88#[cfg(feature = "cohere")]
89pub use cohere::CohereEmbeddingModel;
90
91/// Prelude for common imports.
92pub mod prelude {
93    pub use crate::{
94        cosine_similarity, dot_product, Embedder, Embedding, EmbeddingBatch, EmbeddingError,
95        EmbeddingModel, EmbeddingOutput, EmbeddingResult,
96    };
97
98    #[cfg(feature = "openai")]
99    pub use crate::OpenAIEmbeddingModel;
100
101    #[cfg(feature = "cohere")]
102    pub use crate::CohereEmbeddingModel;
103}
104
105#[cfg(test)]
106mod tests {
107    use super::*;
108
109    #[test]
110    fn test_prelude_imports() {
111        use crate::prelude::*;
112
113        let emb = Embedding::new(vec![1.0, 2.0, 3.0]);
114        assert_eq!(emb.dimensions(), 3);
115    }
116
117    #[test]
118    fn test_similarity_functions() {
119        let a = vec![1.0, 0.0];
120        let b = vec![1.0, 0.0];
121        assert!((cosine_similarity(&a, &b) - 1.0).abs() < 1e-6);
122    }
123}
serdes_ai_embeddings/lib.rs

serdes_ai_embeddings/
lib.rs
