Named(PoolingStrategyName),

Custom {

custom: String,

implementation_revision: String,

},

Mean,

Cls,

LastToken,

WeightedMean,

F32,

F16,

Bf16,

I8,

U8,

Cosine,

Dot,

Euclidean,

Manhattan,

None,

Required,

QueryRecommended,

Custom,

pub schema_version: u16,

pub provider: String,

pub model_id: String,

pub model_artifact_sha256: String,

pub model_graph_sha256: String,

pub tokenizer_sha256: String,

pub prompt_template_sha256: String,

pub pooling_strategy: PoolingStrategy,

pub normalize: bool,

pub truncation_tokens: u32,

pub output_dimension: u32,

pub output_dtype: OutputDtype,

pub runtime_revision: String,

pub distance_metric: EmbeddingDistanceMetric,

pub role_policy: EmbeddingRolePolicy,

pub prefix_policy: PrefixPolicy,

pub prefix_policy_version: u32,

pub fn validate(&self) -> Result<()> {

if self.schema_version != 1 {

return Err(RuvectorError::InvalidParameter(format!(

"unsupported embedding identity schema version {}",

self.schema_version

)));

}

if self.output_dimension == 0

|| self.truncation_tokens == 0

|| self.prefix_policy_version == 0

{

return Err(RuvectorError::InvalidParameter(

"embedding identity dimensions, truncation, and policy version must be positive"

.into(),

));

}

for (name, value) in [

("provider", self.provider.as_str()),

("model_id", self.model_id.as_str()),

("runtime_revision", self.runtime_revision.as_str()),

] {

if value.is_empty() || value.nfc().collect::<String>() != value {

return Err(RuvectorError::InvalidParameter(format!(

"embedding identity {name} must be non-empty NFC"

)));

}

}

for (name, value) in [

("model_artifact_sha256", self.model_artifact_sha256.as_str()),

("model_graph_sha256", self.model_graph_sha256.as_str()),

("tokenizer_sha256", self.tokenizer_sha256.as_str()),

(

"prompt_template_sha256",

self.prompt_template_sha256.as_str(),

),

] {

if value.len() != 64

|| !value

.bytes()

.all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))

{

return Err(RuvectorError::InvalidParameter(format!(

"embedding identity {name} must be lowercase SHA-256 hex"

)));

}

}

Ok(())

}

/// RFC-8785 canonical JSON for this schema. The schema contains no

/// non-integer numbers, so recursively sorting object keys is sufficient.

pub fn canonical_json(&self) -> Result<String> {

self.validate()?;

fn canonical(value: &serde_json::Value, out: &mut String) -> Result<()> {

match value {

serde_json::Value::Null => out.push_str("null"),

serde_json::Value::Bool(v) => out.push_str(if *v { "true" } else { "false" }),

serde_json::Value::Number(v) => out.push_str(&v.to_string()),

serde_json::Value::String(v) => out.push_str(

&serde_json::to_string(v)

.map_err(|e| RuvectorError::SerializationError(e.to_string()))?,

),

serde_json::Value::Array(values) => {

out.push('[');

for (index, item) in values.iter().enumerate() {

if index > 0 {

out.push(',');

}

canonical(item, out)?;

}

out.push(']');

}

serde_json::Value::Object(values) => {

out.push('{');

let mut keys: Vec<_> = values.keys().collect();

keys.sort();

for (index, key) in keys.iter().enumerate() {

if index > 0 {

out.push(',');

}

out.push_str(

&serde_json::to_string(key)

.map_err(|e| RuvectorError::SerializationError(e.to_string()))?,

);

out.push(':');

canonical(&values[*key], out)?;

}

out.push('}');

}

}

Ok(())

}

let value = serde_json::to_value(self)

.map_err(|e| RuvectorError::SerializationError(e.to_string()))?;

let mut output = String::new();

canonical(&value, &mut output)?;

Ok(output)

}

pub fn embedding_space_id(&self) -> Result<String> {

let mut hash = Sha256::new();

hash.update(EMBEDDING_SPACE_DOMAIN);

hash.update(self.canonical_json()?.as_bytes());

Ok(format!("{:x}", hash.finalize()))

}

identity: &EmbeddingSpaceIdentity,

role: EmbeddingRole,

text: &str,

) -> Result<String> {

let text_hash = sha256_hex(text.as_bytes());

let role = match role {

EmbeddingRole::Query => "query",

EmbeddingRole::Passage => "passage",

};

Ok(format!(

"{}:{role}:{text_hash}",

identity.embedding_space_id()?

))

/// Hash covering the canonical query and passage template bundle.

pub fn sha256(&self) -> String {

sha256_hex(format!("query={}\0passage={}", self.query, self.passage).as_bytes())

}

/// Apply the role's template to raw caller text. Providers call this

/// exactly once; high-level callers never prepend prefixes themselves.

pub fn apply(&self, role: EmbeddingRole, text: &str) -> String {

let template = match role {

EmbeddingRole::Query => self.query,

EmbeddingRole::Passage => self.passage,

};

template.replace("{text}", text)

}

aliases: &'static [&'static str],

output_dimension: u32,

role_policy: EmbeddingRolePolicy,

prefix_policy: PrefixPolicy,

templates: PromptTemplates,

MODEL_REGISTRY

.iter()

.find(|entry| entry.aliases.contains(&model_id))

registry_entry(model_id)

.map(|entry| entry.templates)

.ok_or_else(|| {

RuvectorError::InvalidParameter(format!(

"no registered prompt templates for embedding model '{model_id}'"

))

})

identity: &EmbeddingSpaceIdentity,

role: EmbeddingRole,

text: &str,

) -> Result<String> {

match identity.prefix_policy {

PrefixPolicy::None => Ok(text.to_owned()),

PrefixPolicy::Custom => Err(RuvectorError::InvalidParameter(format!(

"model '{}' declares PrefixPolicy::Custom; ruvector has no template for it, so \

identity.model_id

))),

PrefixPolicy::Required | PrefixPolicy::QueryRecommended => {

let templates = registry_prompt_templates(&identity.model_id)?;

if templates.sha256() != identity.prompt_template_sha256 {

return Err(RuvectorError::InvalidParameter(format!(

"prompt template hash for '{}' disagrees with the registry fixture; the \

identity.model_id

)));

}

Ok(templates.apply(role, text))

}

}

provider: &str,

model_id: &str,

dimension: usize,

) -> EmbeddingSpaceIdentity {

let fixture = format!("{provider}\0{model_id}\0v1");

EmbeddingSpaceIdentity {

schema_version: 1,

provider: provider.into(),

model_id: model_id.into(),

model_artifact_sha256: sha256_hex(format!("{fixture}\0artifact").as_bytes()),

model_graph_sha256: sha256_hex(format!("{fixture}\0graph").as_bytes()),

tokenizer_sha256: sha256_hex(format!("{fixture}\0tokenizer").as_bytes()),

prompt_template_sha256: sha256_hex(

format!("{fixture}\0query={{text}}\0passage={{text}}").as_bytes(),

),

pooling_strategy: PoolingStrategy::Named(PoolingStrategyName::Mean),

normalize: true,

truncation_tokens: 512,

output_dimension: dimension as u32,

output_dtype: OutputDtype::F32,

runtime_revision: runtime_revision_for("ruvector-core"),

distance_metric: EmbeddingDistanceMetric::Cosine,

role_policy: EmbeddingRolePolicy::Symmetric,

prefix_policy: PrefixPolicy::None,

prefix_policy_version: 1,

}

provider: &str,

model_id: &str,

dimension: usize,

) -> Result<EmbeddingSpaceIdentity> {

let entry = registry_entry(model_id).ok_or_else(|| {

RuvectorError::InvalidParameter(format!(

"unknown embedding model '{model_id}' requires an explicit complete \

))

})?;

if entry.output_dimension as usize != dimension {

return Err(RuvectorError::InvalidParameter(format!(

"embedding model '{model_id}' is registered at {} dimensions, not {dimension}",

entry.output_dimension

)));

}

let mut identity = default_space_identity(provider, model_id, dimension);

identity.role_policy = entry.role_policy;

identity.prefix_policy = entry.prefix_policy;

identity.prompt_template_sha256 = entry.templates.sha256();

Ok(identity)

pub text_embedding: bool,

pub corpus_mutation: bool,

pub vector_read: bool,

pub inspect: bool,

pub verify: bool,

pub export: bool,

pub fn for_identities(

stored: &EmbeddingSpaceIdentity,

active: &EmbeddingSpaceIdentity,

) -> Result<Self> {

let compatible = stored.embedding_space_id()? == active.embedding_space_id()?;

Ok(Self {

text_embedding: compatible,

corpus_mutation: compatible,

vector_read: true,

inspect: true,

verify: true,

export: true,

})

}

F: Fn(&str) -> Result<Vec<f32>> + Send + Sync,

embed_fn: F,

identity: EmbeddingSpaceIdentity,

name: String,

F: Fn(&str) -> Result<Vec<f32>> + Send + Sync,

pub fn new(

name: impl Into<String>,

identity: EmbeddingSpaceIdentity,

embed_fn: F,

) -> Result<Self> {

identity.validate()?;

if identity.role_policy != EmbeddingRolePolicy::Symmetric {

return Err(RuvectorError::InvalidParameter(

"SymmetricEmbeddingAdapter requires role_policy=symmetric".into(),

));

}

Ok(Self {

embed_fn,

identity,

name: name.into(),

})

}

F: Fn(&str) -> Result<Vec<f32>> + Send + Sync,

fn embed_for(&self, _role: EmbeddingRole, text: &str) -> Result<Vec<f32>> {

(self.embed_fn)(text)

}

fn embedding_space(&self) -> &EmbeddingSpaceIdentity {

&self.identity

}

fn dimensions(&self) -> usize {

self.identity.output_dimension as usize

}

fn name(&self) -> &str {

&self.name

}

fn embed_for(&self, role: EmbeddingRole, text: &str) -> Result<Vec<f32>>;

fn embedding_space(&self) -> &EmbeddingSpaceIdentity;

fn embed_query(&self, text: &str) -> Result<Vec<f32>> {

self.embed_for(EmbeddingRole::Query, text)

}

fn embed_passage(&self, text: &str) -> Result<Vec<f32>> {

self.embed_for(EmbeddingRole::Passage, text)

}

#[deprecated(note = "use embed_query or embed_passage")]

fn embed(&self, text: &str) -> Result<Vec<f32>> {

LEGACY_EMBED_CALLS.fetch_add(1, Ordering::Relaxed);

self.embed_for(EmbeddingRole::Passage, text)

}

fn embed_batch_for(&self, role: EmbeddingRole, texts: &[&str]) -> Result<Vec<Vec<f32>>> {

texts

.iter()

.map(|text| self.embed_for(role, text))

.collect()

}

fn embed_query_batch(&self, texts: &[&str]) -> Result<Vec<Vec<f32>>> {

self.embed_batch_for(EmbeddingRole::Query, texts)

}

fn embed_passage_batch(&self, texts: &[&str]) -> Result<Vec<Vec<f32>>> {

self.embed_batch_for(EmbeddingRole::Passage, texts)

}

/// Get the dimensionality of embeddings produced by this provider

fn dimensions(&self) -> usize;

/// Get a description of this provider (for logging/debugging)

fn name(&self) -> &str;

/// Create a new hash-based embedding provider

pub fn new(dimensions: usize) -> Self {

Self {

dimensions,

identity: default_space_identity("ruvector-hash", "hash-v1", dimensions),

}

}

fn embed_for(&self, _role: EmbeddingRole, text: &str) -> Result<Vec<f32>> {

let mut embedding = vec![0.0; self.dimensions];

let bytes = text.as_bytes();

for (i, byte) in bytes.iter().enumerate() {

embedding[i % self.dimensions] += (*byte as f32) / 255.0;

}

// Normalize

let norm: f32 = embedding.iter().map(|x| x * x).sum::<f32>().sqrt();

if norm > 0.0 {

for val in &mut embedding {

*val /= norm;

}

}

Ok(embedding)

}

fn embedding_space(&self) -> &EmbeddingSpaceIdentity {

&self.identity

}

fn dimensions(&self) -> usize {

self.dimensions

}

fn name(&self) -> &str {

"HashEmbedding (placeholder)"

}

use super::*;

/// Candle-based embedding provider stub

///

/// This is a placeholder. For real implementation:

/// 1. Add candle dependencies for your specific model type

/// 2. Implement model loading and inference

/// 3. Handle tokenization appropriately

///

/// Example structure:

/// ```rust,ignore

/// pub struct CandleEmbedding {

/// model: YourModelType,

/// tokenizer: Tokenizer,

/// device: Device,

/// dimensions: usize,

/// }

/// ```

pub struct CandleEmbedding {

dimensions: usize,

model_id: String,

identity: EmbeddingSpaceIdentity,

}

impl CandleEmbedding {

/// Create a stub candle embedding provider

///

/// **This is not a real implementation!**

/// For production, implement with actual model loading.

///

/// # Example

/// ```rust,no_run

/// # #[cfg(feature = "real-embeddings")]

/// # {

/// use ruvector_core::embeddings::candle::CandleEmbedding;

///

/// // This returns an error - real implementation required

/// let result = CandleEmbedding::from_pretrained(

/// "sentence-transformers/all-MiniLM-L6-v2",

/// false

/// );

/// assert!(result.is_err());

/// # }

/// ```

pub fn from_pretrained(model_id: &str, _use_gpu: bool) -> Result<Self> {

Err(RuvectorError::ModelLoadError(format!(

"Candle embedding support is a stub. Please:\n\

model_id

)))

}

}

impl EmbeddingProvider for CandleEmbedding {

fn embed_for(&self, _role: EmbeddingRole, _text: &str) -> Result<Vec<f32>> {

Err(RuvectorError::ModelInferenceError(

"Candle embedding not implemented - use ApiEmbedding instead".to_string(),

))

}

fn embedding_space(&self) -> &EmbeddingSpaceIdentity {

&self.identity

}

fn dimensions(&self) -> usize {

self.dimensions

}

fn name(&self) -> &str {

"CandleEmbedding (stub - not implemented)"

}

}

api_key: String,

endpoint: String,

model: String,

dimensions: usize,

identity: EmbeddingSpaceIdentity,

client: reqwest::blocking::Client,

/// Create a new API embedding provider

///

/// # Arguments

/// * `api_key` - API key for authentication

/// * `endpoint` - API endpoint URL

/// * `model` - Model identifier

/// * `dimensions` - Expected embedding dimensions

pub fn new(

api_key: String,

endpoint: String,

model: String,

dimensions: usize,

identity: EmbeddingSpaceIdentity,

) -> Result<Self> {

identity.validate()?;

if identity.model_id != model || identity.output_dimension as usize != dimensions {

return Err(RuvectorError::InvalidParameter(

"remote provider identity must match the requested model and dimension".into(),

));

}

// Fail at construction, not on the first embed: a prefix policy this

// provider cannot honor would otherwise send raw text to the API while

// the identity attests that a template was applied. Probing with a

// sample of each role is enough — `apply_prompt_template` is

// deterministic in the identity, not the text.

for role in [EmbeddingRole::Query, EmbeddingRole::Passage] {

apply_prompt_template(&identity, role, "probe")?;

}

Ok(Self {

api_key,

endpoint,

model,

dimensions,

identity,

client: reqwest::blocking::Client::new(),

})

}

/// Create OpenAI embedding provider

///

/// # Models

/// - `text-embedding-3-small` - 1536 dimensions, $0.02/1M tokens

/// - `text-embedding-3-large` - 3072 dimensions, $0.13/1M tokens

/// - `text-embedding-ada-002` - 1536 dimensions (legacy)