polyc-embeddings 0.1.3

//! Provider-agnostic embedding trait for polychrome.
//!
//! This crate defines the [`EmbeddingProvider`] trait that every concrete
//! embedding backend implements. It is the embedding-side analogue of
//! `polyc-llm`'s [`LlmProvider`](https://docs.rs/polyc-llm): a thin
//! seam so the tool-search layer can swap backends — pure-Rust static
//! embeddings (`model2vec-rs`) by default, a heavier transformer
//! (candle + `EmbeddingGemma`) when shallow matching isn't enough — without
//! touching its own code.
//!
//! Tool retrieval is a shallow-semantic task over short strings (a query vs.
//! tool name+description), so the default backend is intentionally tiny and
//! fully deterministic: a fixed lookup table + mean pooling embeds bit-for-bit
//! identically for a pinned model across hardware, which lines up with the
//! reproducible prompt-hash discipline elsewhere in the system.
//!
//! # Modules
//!
//! - [`error`] — the [`EmbeddingError`] bound that [`EmbeddingProvider::Error`]
//!   must satisfy.
//! - [`erased`] — type erasure to a single [`DynEmbeddingProvider`] trait
//!   object, mirroring `polyc-llm`'s `erased` module.

pub mod erased;
pub mod error;

use async_trait::async_trait;

pub use erased::{BoxError, DynEmbeddingProvider, ErasedEmbeddingProvider, into_dyn};
pub use error::EmbeddingError;

/// The seam between the tool-search engine and any concrete embedding backend.
///
/// One implementation per backend, dispatched behind a trait object so the
/// retrieval layer swaps backends without recompiling. The `'static` bound and
/// [`Send`] + [`Sync`] make providers storable in the control plane and
/// shareable across tasks. [`Self::Error`] is bounded by [`EmbeddingError`] so
/// failures are uniform across backends while each keeps its own concrete error.
///
/// `model_id` and `dimensions` are pinned, cheap getters: the `model_id` is
/// recorded in the event log alongside a retrieval set so a result is
/// reproducible, and `dimensions` lets callers size an index without a probe
/// embed.
#[async_trait]
pub trait EmbeddingProvider: Send + Sync + 'static {
    /// The provider's concrete error type. Bounded by [`EmbeddingError`].
    type Error: EmbeddingError;

    /// Stable identifier for the embedding model (e.g. `"potion-base-8M"`).
    ///
    /// Pinned per backend instance and recorded next to any retrieval set so
    /// the result can be reproduced. Two providers with the same `model_id`
    /// must produce comparable vectors.
    fn model_id(&self) -> &str;

    /// Dimensionality of the vectors this provider produces.
    fn dimensions(&self) -> usize;

    /// Embed a batch of texts, returning one vector per input in order.
    ///
    /// Batched because the static backend amortises almost nothing per-call but
    /// callers (indexing a connector's whole tool catalogue) embed many short
    /// strings at once. Each returned vector has [`Self::dimensions`] elements.
    ///
    /// # Errors
    ///
    /// Returns [`Self::Error`] if the model cannot embed the batch (e.g. an
    /// uninitialised model or, for transformer backends, a tokenisation fault).
    async fn embed(&self, texts: &[String]) -> Result<Vec<Vec<f32>>, Self::Error>;
}