kyma_embed/lib.rs
1//! Embedding primitives for kyma.
2//!
3//! `EmbeddingBackend` is the single trait. The default impl is
4//! `FastembedBackend` (ONNX, runs in-process, no external service).
5//! Provider-backed impls (Ollama, OpenAI-compatible, Gemini) are
6//! feature-gated.
7
8#![forbid(unsafe_code)]
9
10pub mod config;
11pub mod errors;
12
13#[cfg(feature = "fastembed-backend")]
14pub mod fastembed;
15
16#[cfg(feature = "ollama")]
17pub mod ollama;
18
19#[cfg(feature = "openai-compat")]
20pub mod openai_compat;
21
22#[cfg(feature = "gemini")]
23pub mod gemini;
24
25pub use config::{EmbeddingConfig, EmbeddingProvider};
26pub use errors::EmbedError;
27
28use async_trait::async_trait;
29
30/// Turns text into dense vectors.
31///
32/// Implementations MUST be deterministic for the same input when
33/// `backend.id()` stays the same — this is a load-bearing property
34/// of the kyma replay cache.
35#[async_trait]
36pub trait EmbeddingBackend: Send + Sync + std::fmt::Debug {
37 /// Stable identifier, e.g. `"fastembed/bge-small-en-v1.5"` or
38 /// `"openai/text-embedding-3-small"`. Mixing IDs across writes
39 /// is a correctness bug (distance-space mismatch) — the engine
40 /// tags every vector column with its `model_id`.
41 fn id(&self) -> &str;
42
43 /// Output dimension. Must be stable for the lifetime of the instance.
44 fn dimension(&self) -> u16;
45
46 /// Compute embeddings for a batch. Order of outputs matches inputs.
47 async fn embed(&self, texts: &[String]) -> Result<Vec<Vec<f32>>, EmbedError>;
48}
49
50#[cfg(feature = "fastembed-backend")]
51pub use fastembed::FastembedBackend;
52
53#[cfg(feature = "ollama")]
54pub use ollama::OllamaBackend;
55
56#[cfg(feature = "openai-compat")]
57pub use openai_compat::OpenAICompatBackend;
58
59#[cfg(feature = "gemini")]
60pub use gemini::GeminiBackend;