Embedder

Pluggable text embedding with multiple provider support.

Embedder

Bases: ABC

Abstract base for text embedding providers.

Subclasses must implement dimension and embed. Override embed_batch for providers that support batched requests natively.

dimension abstractmethod property

dimension: int

Dimensionality of the embedding vectors.

supported_models classmethod

supported_models() -> list[ModelSpec]

Static catalogue of models this subclass officially supports.

Returns [] by default. Subclasses that target paid providers with a known fixed model list (OpenAI, Gemini, Voyage, ...) should override this so spkt init can render a picker without hardcoding a registry in core.

Local-server subclasses (LM Studio, Ollama) should leave this empty and rely on :meth:detect_dimension instead — the user already chose the model on the server side.

detect_dimension async

detect_dimension() -> int

Probe the live endpoint to determine the embedding dimension.

Calls :meth:embed once with a tiny payload and returns the length of the resulting vector. Useful for spkt init and similar tooling that wants to fill in dimension automatically without making the user count it themselves.

Subclasses do not normally need to override this — but a provider that bills per call (OpenAI, Gemini, etc.) is expected to refuse the probe and rely on :meth:supported_models instead, so the metered providers don't surprise users with a cost during spkt init.

embed abstractmethod async

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

Embed a single text string.

Parameters:

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

Returns:

Type	Description
list[float]	Vector of floats with length equal to dimension.

embed_batch async

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

Embed multiple texts.

Default implementation calls embed() sequentially. Override for providers that support native batching.

Parameters:

Name	Type	Description	Default
texts	list[str]	List of input texts.	required

Returns:

Type	Description
list[list[float]]	List of embedding vectors, one per input text.

apply_prefix

apply_prefix(text: str, embedding_type: EmbeddingType) -> str

Prepend a task-type prefix appropriate for this provider.

The default implementation is a no-op. Subclasses whose models benefit from task-type prefixes (e.g. Nomic, Cohere) should override this or accept a prefix_style at construction time.

Parameters:

Name	Type	Description	Default
text	str	Raw text to embed.	required
embedding_type	EmbeddingType	Whether the text is a stored document or a query.	required

Returns:

Type	Description
str	Text with the appropriate prefix prepended (or unchanged).

OpenAICompatEmbedder

OpenAICompatEmbedder(*, base_url: str = 'http://localhost:1234/v1', model: str = 'text-embedding-nomic-embed-text-v1.5', dimension: int = 768, api_key: str = 'not-needed', timeout: float = 30.0, prefix_style: str = 'none')

Bases: Embedder

Embedder using any OpenAI-compatible /v1/embeddings endpoint.

Works with LM Studio, Ollama (/v1), vLLM, OpenAI, and any service that implements the OpenAI embeddings API.

Example

embedder = OpenAICompatEmbedder(
    base_url="http://localhost:1234/v1",
    model="text-embedding-nomic-embed-text-v1.5",
    dimension=768,
    prefix_style="nomic",
)
vec = await embedder.embed("hello world")

Parameters:

Name	Type	Description	Default
base_url	str	API base URL (without trailing slash).	'http://localhost:1234/v1'
model	str	Model identifier.	'text-embedding-nomic-embed-text-v1.5'
dimension	int	Expected embedding dimension.	768
api_key	str	Bearer token (default "not-needed" for local servers).	'not-needed'
timeout	float	HTTP request timeout in seconds.	30.0
prefix_style	str	Task-type prefix style. Pick the one that matches your model family — using the wrong prefix silently degrades retrieval quality. "nomic" → search_document: / search_query: (Nomic AI nomic-embed-text-v1.5 and friends) "cohere" → search_document: / search_query: (Cohere embed-english-v3.0 etc., same surface as Nomic) "e5" → passage: / query: (intfloat e5-large-v2, multilingual-e5-large-instruct, ...) "mxbai" → empty / Represent this sentence for searching relevant passages: (MixedBread AI mxbai-embed-large-v1) "bge" → empty / Represent this sentence for searching relevant passages: (BAAI bge-large-en-v1.5; bge-m3 does not need a prefix — use "none" instead) "none" (default) → no prefix	'none'

OllamaEmbedder

OllamaEmbedder(*, base_url: str = 'http://localhost:11434', model: str = 'nomic-embed-text', dimension: int = 768, timeout: float = 30.0, prefix_style: str = 'none')

Bases: Embedder

Embedder using Ollama's native /api/embed endpoint.

Use this when connecting directly to Ollama without the OpenAI compatibility layer.

Example

embedder = OllamaEmbedder(
    base_url="http://localhost:11434",
    model="nomic-embed-text",
    dimension=768,
    prefix_style="nomic",
)

Parameters:

Name	Type	Description	Default
base_url	str	Ollama server URL.	'http://localhost:11434'
model	str	Model name as shown in ollama list.	'nomic-embed-text'
dimension	int	Expected embedding dimension.	768
timeout	float	HTTP request timeout in seconds.	30.0
prefix_style	str	Task-type prefix style (same as OpenAICompatEmbedder).	'none'

NullEmbedder

NullEmbedder(dimension: int = 768)

Bases: Embedder

Returns zero vectors. For testing and when no provider is configured.

Parameters:

Name	Type	Description	Default
dimension	int	Vector dimension (default 768).	768

Factory

create_embedder

create_embedder(provider: str, *, base_url: str = '', model: str = '', dimension: int = 768, api_key: str = 'not-needed', timeout: float = 30.0, prefix_style: str = 'none') -> Embedder | None

Factory: create an Embedder from config values.

Parameters:

Name	Type	Description	Default
provider	str	"openai-compat", "ollama", or "none".	required
base_url	str	API base URL.	''
model	str	Model identifier.	''
dimension	int	Embedding dimension.	768
api_key	str	Bearer token (OpenAI-compat only).	'not-needed'
timeout	float	HTTP timeout in seconds.	30.0
prefix_style	str	Task-type prefix style. One of "nomic", "cohere", "e5", "mxbai", "bge", or "none". See OpenAICompatEmbedder for the per-style mapping.	'none'

Returns:

Type	Description
Embedder | None	An Embedder instance, or None if provider is "none".

Raises:

Type	Description
ValueError	If the provider is unknown.

Serialization Helpers

vec_to_blob

vec_to_blob(vec: list[float]) -> bytes

Pack a float list into a little-endian binary blob for sqlite-vec.

Parameters:

Name	Type	Description	Default
vec	list[float]	Embedding vector.	required

Returns:

Type	Description
bytes	Binary blob suitable for INSERT INTO neuron_vec.

blob_to_vec

blob_to_vec(blob: bytes) -> list[float]

Unpack a sqlite-vec binary blob into a float list.

Parameters:

Name	Type	Description	Default
blob	bytes	Binary blob from sqlite-vec.	required

Returns:

Type	Description
list[float]	List of floats.