Embeddings

Factory

memory_reuse.embeddings.create_embedder

create_embedder(config: CacheConfig) -> EmbeddingProvider

Create an :class:EmbeddingProvider from a cache configuration.

The provider is selected by :attr:CacheConfig.embedding_provider and configured with :attr:CacheConfig.embedding_model (when set). Concrete provider modules are imported lazily so their optional dependencies are only required when that provider is actually selected.

Parameters:

Name	Type	Description	Default
config	CacheConfig	The cache configuration. Its embedding_provider field selects the implementation.	required

Returns:

Type	Description
EmbeddingProvider	A concrete :class:EmbeddingProvider instance.

Raises:

Type	Description
ConfigurationError	If embedding_provider is None or is not one of the supported values.

EmbeddingProvider (interface)

memory_reuse.embeddings.base.EmbeddingProvider

Bases: ABC

Interface that all embedding providers must implement.

The :attr:identity string namespaces stored vectors so embeddings from different providers or models are never compared, and :attr:dimension lets callers validate vector shape before a similarity search.

Implementors should raise :class:~memory_reuse.exceptions.EmbeddingProviderError (with an install hint) when their optional dependency is missing, and should keep :attr:identity stable for a given provider+model pairing.

identity abstractmethod property

identity: str

Return the stable "provider:model" identity string.

This value namespaces stored vectors so that embeddings produced by different providers or models are never compared against one another (for example "openai:text-embedding-3-small").

Returns:

Type	Description
str	The provider+model identity string.

dimension abstractmethod property

dimension: int

Return the dimensionality of the produced embedding vectors.

Returns:

Type	Description
int	The number of floats in each embedding vector.

embed abstractmethod async

embed(text: str) -> list[float]

Return the embedding vector for a single piece of text.

Parameters:

Name	Type	Description	Default
text	str	The text to embed.	required

Returns:

Type	Description
list[float]	The embedding vector as a list of floats of length
list[float]	attr:dimension.

embed_batch async

embed_batch(texts: list[str]) -> list[list[float]]

Return embedding vectors for multiple texts.

The default implementation calls :meth:embed sequentially. Providers that support a native batch call should override this for efficiency.

Parameters:

Name	Type	Description	Default
texts	list[str]	The texts to embed.	required

Returns:

Type	Description
list[list[float]]	A list of embedding vectors, one per input text, in the same
list[list[float]]	order as texts.

LocalEmbedder

memory_reuse.embeddings.local.LocalEmbedder

LocalEmbedder(model: str | None = None)

Bases: EmbeddingProvider

Embedding provider backed by a local sentence-transformers model.

The heavy sentence-transformers dependency and the model itself are loaded lazily on first use, so constructing a :class:LocalEmbedder is cheap and importing this module has no import-time side effects.

Parameters:

Name	Type	Description	Default
model	str | None	The sentence-transformers model name to load. None selects a small, fast default ("all-MiniLM-L6-v2").	None

Raises:

Type	Description
EmbeddingProviderError	On first use, if sentence-transformers is not installed.

identity property

identity: str

Return the stable "local:<model>" identity string.

Returns:

Type	Description
str	The provider+model identity, e.g. "local:all-MiniLM-L6-v2".

dimension property

dimension: int

Return the dimensionality of the produced embedding vectors.

Loads the model on first access to query its true output dimension.

Returns:

Type	Description
int	The number of floats in each embedding vector.

Raises:

Type	Description
EmbeddingProviderError	If sentence-transformers is not installed.

embed async

embed(text: str) -> list[float]

Return the embedding vector for a single piece of text.

The synchronous, potentially CPU-bound model call is run in a worker thread so it does not block the event loop.

Parameters:

Name	Type	Description	Default
text	str	The text to embed.	required

Returns:

Type	Description
list[float]	The embedding vector as a list of floats of length
list[float]	attr:dimension.

Raises:

Type	Description
EmbeddingProviderError	If sentence-transformers is not installed.

embed_batch async

embed_batch(texts: list[str]) -> list[list[float]]

Return embedding vectors for multiple texts in a single model call.

sentence-transformers encodes batches efficiently, so this overrides the default sequential implementation.

Parameters:

Name	Type	Description	Default
texts	list[str]	The texts to embed.	required

Returns:

Type	Description
list[list[float]]	A list of embedding vectors, one per input text, in the same order
list[list[float]]	as texts.

Raises:

Type	Description
EmbeddingProviderError	If sentence-transformers is not installed.

OpenAIEmbedder

memory_reuse.embeddings.openai.OpenAIEmbedder

OpenAIEmbedder(model: str | None = None, api_key: str | None = None)

Bases: EmbeddingProvider

Embedding provider backed by OpenAI's hosted embeddings API.

The openai dependency and the API client are created lazily on first use, so constructing an :class:OpenAIEmbedder is cheap and importing this module has no import-time side effects.

Parameters:

Name	Type	Description	Default
model	str | None	The OpenAI embedding model name. None selects a small, low-cost default ("text-embedding-3-small").	None
api_key	str | None	An explicit API key. None lets the openai client read it from the environment (OPENAI_API_KEY).	None

Raises:

Type	Description
EmbeddingProviderError	On first use, if openai is not installed.

identity property

identity: str

Return the stable "openai:<model>" identity string.

Returns:

Type	Description
str	The provider+model identity, e.g. "openai:text-embedding-3-small".

dimension property

dimension: int

Return the dimensionality of the produced embedding vectors.

The value is looked up from a table of known OpenAI embedding models, so no network call is made. Unknown models fall back to the default model's dimension.

Returns:

Type	Description
int	The number of floats in each embedding vector.

embed async

embed(text: str) -> list[float]

Return the embedding vector for a single piece of text.

Parameters:

Name	Type	Description	Default
text	str	The text to embed.	required

Returns:

Type	Description
list[float]	The embedding vector as a list of floats of length
list[float]	attr:dimension.

Raises:

Type	Description
EmbeddingProviderError	If openai is not installed.

embed_batch async

embed_batch(texts: list[str]) -> list[list[float]]

Return embedding vectors for multiple texts in a single API call.

The OpenAI embeddings API accepts a list of inputs, so this overrides the default sequential implementation to reduce the number of requests.

Parameters:

Name	Type	Description	Default
texts	list[str]	The texts to embed.	required

Returns:

Type	Description
list[list[float]]	A list of embedding vectors, one per input text, in the same order
list[list[float]]	as texts.

Raises:

Type	Description
EmbeddingProviderError	If openai is not installed.

LiteLLMEmbedder

memory_reuse.embeddings.litellm.LiteLLMEmbedder

LiteLLMEmbedder(model: str | None = None)

Bases: EmbeddingProvider

Embedding provider backed by LiteLLM's uniform embedding API.

LiteLLM routes to whichever backend the model string names, so a single provider class covers AWS Bedrock, OpenAI, Cohere, and every other LiteLLM-supported embedding model. The heavy litellm dependency is imported lazily on first use, so constructing a :class:LiteLLMEmbedder is cheap and importing this module has no import-time side effects.

Because the embedding dimension depends on the underlying model (and is only known reliably after a call), :attr:dimension is discovered from the first embedding response and cached.

Parameters:

Name	Type	Description	Default
model	str | None	The LiteLLM model string, e.g. "text-embedding-3-small" or "bedrock/amazon.titan-embed-text-v2". None selects a low-cost default ("text-embedding-3-small").	None

Raises:

Type	Description
EmbeddingProviderError	On first use, if litellm is not installed.

identity property

identity: str

Return the stable "litellm:<model>" identity string.

Returns:

Type	Description
str	The provider+model identity, e.g.
str	"litellm:bedrock/amazon.titan-embed-text-v2".

dimension property

dimension: int

Return the dimensionality of the produced embedding vectors.

LiteLLM abstracts over many models whose dimensionality differs and is not known without a call, so the dimension is discovered lazily from the first :meth:embed / :meth:embed_batch response and cached. Calling this before any embedding has been produced raises :class:EmbeddingProviderError.

Returns:

Type	Description
int	The number of floats in each embedding vector.

Raises:

Type	Description
EmbeddingProviderError	If no embedding has been produced yet, so the dimension is not yet known.

embed async

embed(text: str) -> list[float]

Return the embedding vector for a single piece of text.

Parameters:

Name	Type	Description	Default
text	str	The text to embed.	required

Returns:

Type	Description
list[float]	The embedding vector as a list of floats of length
list[float]	attr:dimension.

Raises:

Type	Description
EmbeddingProviderError	If litellm is not installed.

embed_batch async

embed_batch(texts: list[str]) -> list[list[float]]

Return embedding vectors for multiple texts in a single API call.

LiteLLM's embedding API accepts a list of inputs, so this overrides the default sequential implementation to reduce the number of requests.

Parameters:

Name	Type	Description	Default
texts	list[str]	The texts to embed.	required

Returns:

Type	Description
list[list[float]]	A list of embedding vectors, one per input text, in the same order
list[list[float]]	as texts.

Raises:

Type	Description
EmbeddingProviderError	If litellm is not installed.