localvectordb.embeddings module

Plugin-based embedding providers for LocalVectorDB v1.0

This module provides a flexible embedding system with support for multiple providers through a registry pattern.

class localvectordb.embeddings.EmbeddingProvider(model: str, *, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, **kwargs: Any)

Bases: ABC

Abstract base class for embedding providers.

__init__(model: str, *, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, **kwargs: Any) → None
property async_supported: bool
async embed_batch(texts: List[str], batch_size: int | None = None, progress_callback: Callable | None = None) → ndarray

Generate embeddings with automatic retry handling.

async embed_async(texts: List[str], batch_size: int | None = None) → ndarray

Generate embeddings for a list of texts.

abstractmethod get_dimension() → int

Get the embedding dimension for this model

abstractmethod validate_model() → bool

Check if the model is available/valid

abstract property provider_name: str

Return the provider name

abstract property max_batch_size: int

Maximum batch size for this provider

embed_sync(texts: List[str], batch_size: int | None = None) → ndarray

Synchronous wrapper for embed_batch with proper event loop handling.

class localvectordb.embeddings.HTTPEmbeddingProvider(model: str, *, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, base_url: str | None = None, **kwargs: Any)

Bases: EmbeddingProvider, ABC

Embedding Providers which utilize HTTP requests to get embeddings.

Subclasses need to implement _embed_single_batch(self, texts: list[str], client: httpx.AsyncClient) which provides an async httpx client to use to make the http request.

property max_input_tokens: int | None

Maximum input tokens per text. Override in subclasses.

Returns None if no limit is enforced at the provider level.

__init__(model: str, *, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, base_url: str | None = None, **kwargs: Any)
class localvectordb.embeddings.OllamaEmbeddings(model: str, *, timeout: int = 300, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 3, base_url: str | None = None, requested_dimensions: int | None = None, normalize: bool = False, num_ctx: int | None = None, num_batch: int | None = None, truncate: bool = True)

Bases: HTTPEmbeddingProvider

Ollama embedding provider.

Parameters:

  • model (str) – The OpenAI model to use for embeddding

  • base_url (str) – The base url for the ollama server (default http://127.0.0.1:11434, matching Ollama’s default bind address). Alternatively, you can set the OLLAMA_URL environment variable.

  • timeout (int, default = 90) – Timeout in seconds for the http request

  • max_retries (int, default = 3) – How many times to retry on a failed request.

  • retry_delay (float, default = 1.0) – How long to delay after a failed request (the backoff is exponential)

  • max_concurrent_requests (int, default = 3) – How many requests to make concurrently to the ollama server.

  • num_ctx (int, optional) – Context window (options.num_ctx) to request from Ollama. Ollama loads each model at a default num_ctx (often 2048) regardless of the model’s nominal maximum, and silently truncates longer inputs; set this to embed longer inputs in full (e.g. 8192 for bge-m3). When None, Ollama’s per-model default applies.

  • num_batch (int, optional) – Batch size (options.num_batch -> llama.cpp n_batch). This is the real ceiling for embeddings: an encoder (non-causal) model embeds the whole input in a single batch, so an input longer than n_batch (default 2048) is silently truncated regardless of num_ctx. Raising num_ctx alone therefore does nothing for embeddings past 2048 – n_batch (undocumented for /api/embed) must move too. When None but num_ctx is set, this defaults to num_ctx so a raised context actually takes effect; pass an explicit value to decouple them.

  • truncate (bool, default = True) – Whether Ollama truncates an input that exceeds the batch/context window. The default (True) matches Ollama’s own default and avoids a hard error on an over-long input; set False to make an over-long input fail loudly.

__init__(model: str, *, timeout: int = 300, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 3, base_url: str | None = None, requested_dimensions: int | None = None, normalize: bool = False, num_ctx: int | None = None, num_batch: int | None = None, truncate: bool = True) → None
property provider_name: str

Return the provider name

property max_batch_size: int

Maximum batch size for this provider

validate_model() → bool

Check if the model is available in Ollama

get_dimension() → int

Get embedding dimension by making a test call

class localvectordb.embeddings.OpenAIEmbeddings(model: str, *, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, api_key: str | None = None, base_url: str | None = None, requested_dimensions: int | None = None, normalize: bool = False)

Bases: HTTPEmbeddingProvider

OpenAI embedding provider.

Parameters:

  • model (str) – The OpenAI model to use for embedding

  • api_key (str, optional) – Optionally provide the api key as a str. If not provided, tries to use “OPENAI_API_KEY” environment variable. You can specify a custom environment variable to use by prefixing with a “$”, for example using: apikey=”$CUSTOM_ENV_VAR” would try to load the api key from the CUSTOM_ENV_VAR environment variable.

  • timeout (int, default = 90) – Timeout in seconds for the http request

  • max_retries (int, default = 3) – How many times to retry on a failed request.

  • retry_delay (float, default = 1.0) – How long to delay after a failed request (the backoff is exponential)

  • max_concurrent_requests (int, default = 5) – How many requests to make concurrently to the OpenAI server.

__init__(model: str, *, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, api_key: str | None = None, base_url: str | None = None, requested_dimensions: int | None = None, normalize: bool = False) → None
property provider_name: str

Return the provider name

property max_batch_size: int

Maximum batch size for this provider

property max_input_tokens: int

Maximum input tokens per text for this model.

validate_model() → bool

Check if the model exists

get_dimension() → int

Get embedding dimension

class localvectordb.embeddings.GoogleEmbeddings(model: str = 'gemini-embedding-001', *, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, api_key: str | None = None, task_type: Literal['semantic_similarity', 'classification', 'clustering', 'retrieval_document', 'retrieval_query', 'code_retrieval_query', 'question_answering', 'fact_verification'] = 'semantic_similarity', requested_dimensions: int | None = None, normalize: bool = True, base_url: str | None = None, **kwargs: Any)

Bases: HTTPEmbeddingProvider

Google AI (Gemini) embedding provider using the Generative Language API.

Parameters:

  • model (str, default "gemini-embedding-001") – The Google AI embedding model, e.g.: - “gemini-embedding-001” (stable) - “gemini-embedding-exp-03-07” (experimental)

  • api_key (str, optional) – API key string or an env var reference (e.g., “$GEMINI_API_KEY”). If not provided, tries env vars (in order): GEMINI_API_KEY, GOOGLE_API_KEY.

  • task_type (Literal, optional) – One of: {“semantic_similarity”, “classification”, “clustering”, “retrieval_document”, “retrieval_query”, “code_retrieval_query”, “question_answering”, “fact_verification”} See: https://ai.google.dev/gemini-api/docs/embeddings#supported-task-types

  • requested_dimensions (int, optional) – MRL-controlled output size (128–3072). Defaults to 3072 if not set by API. If provided, get_dimension() returns this value without a test call.

  • normalize (bool, default False) – If True, L2-normalize returned vectors (recommended for non-3072 outputs). For 3072 output, vectors are already normalized by the API.

  • base_url (str, optional) – Override the base API URL. Defaults to the public Google endpoint.

  • timeout (int, default 90) – Request timeout in seconds.

  • max_retries (int, default 3) – Retry attempts on transient errors.

  • retry_delay (float, default 1.0) – Base delay between retries (exponential backoff).

  • max_concurrent_requests (int, default 5) – Concurrency for batch processing.

__init__(model: str = 'gemini-embedding-001', *, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, api_key: str | None = None, task_type: Literal['semantic_similarity', 'classification', 'clustering', 'retrieval_document', 'retrieval_query', 'code_retrieval_query', 'question_answering', 'fact_verification'] = 'semantic_similarity', requested_dimensions: int | None = None, normalize: bool = True, base_url: str | None = None, **kwargs: Any) → None
property provider_name: str

Return the provider name

property max_batch_size: int

Maximum batch size for this provider

validate_model() → bool

Validate the model by querying the models endpoint.

get_dimension() → int

Return embedding dimension, using API probe if needed.

class localvectordb.embeddings.JinaEmbeddings(model: str, *, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, api_key: str | None = None, task: str | None = 'auto', truncate: bool = False, late_chunking: bool = False, requested_dimensions: int | None = None, **kwargs: Any)

Bases: HTTPEmbeddingProvider

Jina AI embedding provider.

Parameters:

  • model (str) –

    The Jina model to use for embedding. Examples:

    • ”jina-embeddings-v4” (multimodal/multilingual, 2048 dims)

    • ”jina-embeddings-v3” (1024 dims)

    • ”jina-clip-v2” (1024 dims)

    • ”jina-code-embeddings-0.5b”

    • ”jina-code-embeddings-1.5b”

  • api_key (str, optional) – Optionally provide the API key as a str. If it starts with “$” and the rest is uppercase, the key will be read from that environment variable. Otherwise, defaults to JINA_API_KEY env var. Get your Jina AI API key for free: https://jina.ai/?sui=apikey

  • timeout (int, default = 90) – HTTP timeout (seconds)

  • max_retries (int, default = 3) – Automatic retry attempts

  • retry_delay (float, default = 1.0) – Base delay for exponential backoff

  • max_concurrent_requests (int, default = 5) – Concurrent requests to Jina API

  • body (Additional keyword arguments are passed through to the Jina Embeddings API request) –

    • embedding_type: str, default “float” (other options: “base64”, “binary”, “ubinary”)

    • task: str, e.g., for v4: “retrieval.query” | “retrieval.passage” |

      ”text-matching” | “code.query” | “code.passage”; for code models: “nl2code.query” | “nl2code.passage” | “code2code.query” | “code2code.passage” | “code2nl.query” | “code2nl.passage” | “code2completion.query” | “code2completion.passage” | “qa.query” | “qa.passage”

    • dimensions: int, to truncate output embeddings to this size

    • truncate: bool

    • late_chunking: bool (v4)

    • return_multivector: bool (v4; not supported by this provider, will raise if True)

    • normalized: bool (v3)

  • example (for) –

    • embedding_type: str, default “float” (other options: “base64”, “binary”, “ubinary”)

    • task: str, e.g., for v4: “retrieval.query” | “retrieval.passage” |

      ”text-matching” | “code.query” | “code.passage”; for code models: “nl2code.query” | “nl2code.passage” | “code2code.query” | “code2code.passage” | “code2nl.query” | “code2nl.passage” | “code2completion.query” | “code2completion.passage” | “qa.query” | “qa.passage”

    • dimensions: int, to truncate output embeddings to this size

    • truncate: bool

    • late_chunking: bool (v4)

    • return_multivector: bool (v4; not supported by this provider, will raise if True)

    • normalized: bool (v3)

  • Behavior

  • --------

  • default (- By)

  • vectors. (embeddings are returned as float)

  • dimensions (- If you provide) –

    1. tell the API to output that dimension; and

    2. use that value to pre-allocate output arrays.

  • both (this provider will) –

    1. tell the API to output that dimension; and

    2. use that value to pre-allocate output arrays.

  • provided (- If no dimensions is) – Otherwise, dimension is determined via a one-off probe request.

  • (v4=2048 (well-known models use known sizes) – Otherwise, dimension is determined via a one-off probe request.

  • v3=1024 – Otherwise, dimension is determined via a one-off probe request.

  • clip-v2=1024). – Otherwise, dimension is determined via a one-off probe request.

__init__(model: str, *, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, api_key: str | None = None, task: str | None = 'auto', truncate: bool = False, late_chunking: bool = False, requested_dimensions: int | None = None, **kwargs: Any) → None
property provider_name: str

Return the provider name

property max_batch_size: int

Maximum batch size for this provider

validate_model() → bool

Try a lightweight probe to confirm the model is usable.

get_dimension() → int

Return embedding dimension. Uses known sizes, user-requested dimensions, or probes via API.

class localvectordb.embeddings.SentenceTransformerEmbeddings(model: str, *, device: str | None = None, normalize: bool = True, requested_dimensions: int | None = None, trust_remote_code: bool = False, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, **kwargs: Any)

Bases: EmbeddingProvider

SentenceTransformers embedding provider for local inference.

Parameters:

  • model (str) – The SentenceTransformer model name (e.g., “all-MiniLM-L6-v2”).

  • device (str, optional) – Device for inference (cpu/cuda/mps/auto). Default: auto-detect.

  • normalize (bool) – Whether to L2-normalize embeddings. Default: True.

  • requested_dimensions (int, optional) – Truncate embeddings to this dimension (Matryoshka support).

  • trust_remote_code (bool) – Whether to trust remote code when loading models. Default: False.

__init__(model: str, *, device: str | None = None, normalize: bool = True, requested_dimensions: int | None = None, trust_remote_code: bool = False, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, **kwargs: Any) → None
property provider_name: str

Return the provider name

property max_batch_size: int

Maximum batch size for this provider

validate_model() → bool

Check if the model is available/valid

get_dimension() → int

Get the embedding dimension for this model

class localvectordb.embeddings.HuggingFaceInferenceEmbeddings(model: str, *, api_key: str | None = None, base_url: str | None = None, normalize: bool = True, requested_dimensions: int | None = None, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, **kwargs: Any)

Bases: HTTPEmbeddingProvider

HuggingFace Inference API embedding provider.

Parameters:

  • model (str) – HuggingFace model ID (e.g., “BAAI/bge-small-en-v1.5”).

  • api_key (str, optional) – API key. Falls back to HF_TOKEN / HUGGINGFACE_TOKEN env vars.

  • base_url (str, optional) – Base URL. Default: https://api-inference.huggingface.co

  • normalize (bool) – Whether to L2-normalize embeddings. Default: True.

  • requested_dimensions (int, optional) – Truncate embeddings to this dimension.

__init__(model: str, *, api_key: str | None = None, base_url: str | None = None, normalize: bool = True, requested_dimensions: int | None = None, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_requests: int = 5, **kwargs: Any) → None
property provider_name: str

Return the provider name

property max_batch_size: int

Maximum batch size for this provider

validate_model() → bool

Check if the model is available/valid

get_dimension() → int

Get the embedding dimension for this model

class localvectordb.embeddings.HuggingFaceLocalEmbeddings(model: str, *, device: str | None = None, normalize: bool = True, requested_dimensions: int | None = None, trust_remote_code: bool = False, pooling_strategy: str = 'mean', timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, **kwargs: Any)

Bases: EmbeddingProvider

Local HuggingFace transformers embedding provider.

Parameters:

  • model (str) – HuggingFace model ID (e.g., “BAAI/bge-small-en-v1.5”).

  • device (str, optional) – Device for inference (cpu/cuda/mps). Default: auto-detect.

  • normalize (bool) – Whether to L2-normalize embeddings. Default: True.

  • requested_dimensions (int, optional) – Truncate embeddings to this dimension.

  • trust_remote_code (bool) – Whether to trust remote code. Default: False.

  • pooling_strategy (str) – Pooling strategy: “mean”, “cls”, or “max”. Default: “mean”.

__init__(model: str, *, device: str | None = None, normalize: bool = True, requested_dimensions: int | None = None, trust_remote_code: bool = False, pooling_strategy: str = 'mean', timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, **kwargs: Any) → None
property provider_name: str

Return the provider name

property max_batch_size: int

Maximum batch size for this provider

validate_model() → bool

Check if the model is available/valid

get_dimension() → int

Get the embedding dimension for this model

class localvectordb.embeddings.MockEmbeddings(model: str, dimension: int = 384, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, **kwargs: Any)

Bases: EmbeddingProvider

Mock embedding provider for testing

__init__(model: str, dimension: int = 384, timeout: int = 90, max_retries: int = 3, retry_delay: float = 1.0, **kwargs: Any) → None
property provider_name: str

Return the provider name

property max_batch_size: int

Maximum batch size for this provider

validate_model() → bool

Check if the model is available/valid

get_dimension() → int

Get the embedding dimension for this model

class localvectordb.embeddings.EmbeddingRegistry

Bases: object

Registry for embedding providers with plugin discovery

classmethod register(name: str, provider_class: Type[EmbeddingProvider]) → None

Register a new embedding provider

classmethod get(name: str) → Type[EmbeddingProvider]

Get an embedding provider by name

classmethod create_provider(provider_name: str, model: str, **kwargs: Any) → EmbeddingProvider

Create an embedding provider instance

classmethod list() → List[str]

List all registered providers

classmethod refresh_plugins() → None

Force re-discovery of plugins (useful for testing)

localvectordb.embeddings.create_embedding_provider(provider: str, model: str, **kwargs: Any) → EmbeddingProvider

Create an embedding provider instance

localvectordb.embeddings.list_providers() → List[str]

List available embedding providers

async localvectordb.embeddings.embed_texts(texts: List[str], provider: str, model: str, batch_size: int | None = None, **provider_kwargs: Any) → ndarray

Convenience function to embed texts

localvectordb.embeddings.embed_texts_sync(texts: List[str], provider: str, model: str, batch_size: int | None = None, **provider_kwargs: Any) → ndarray

Synchronous convenience function to embed texts