vd.util

The backend registry, the connect() factory, and small shared utilities.

This module is intentionally thin. It owns three things:

• the registry mapping a backend name ("chroma", "qdrant", …) to its adapter Client class, via the register_backend() decorator;

• connect(), the one entry point users call to get a client;

• backend-agnostic helpers: document-input normalization, search-result egress functions, and vector math.

Everything descriptive about a backend (pip package, license, docs URLs, deployment archetype, setup checks) lives in vd.providers and its data file, not here.

Functions

connect(backend, *[, embedder])	Connect to a vector database backend and return its Client.
cosine_similarity(vec1, vec2)	Cosine similarity of two vectors (1.0 identical, 0.0 orthogonal).
euclidean_distance(vec1, vec2)	Euclidean (L2) distance between two vectors.
get_backend(name)	Return the adapter Client class registered under name.
id_and_score(result)	Egress: keep (id, score).
id_only(result)	Egress: keep only the document id.
id_text_score(result)	Egress: keep (id, text, score).
list_backends()	Return the names of all backends with a registered (importable) adapter.
mean_vector(vectors)	Component-wise mean of a non-empty iterable of equal-length vectors.
normalize_document_input(doc_input, *[, auto_id])	Normalize a flexible document input to a Document.
register_backend(name)	Class decorator: register an adapter Client under name.
text_only(result)	Egress: keep only the text.

vd.util.connect(backend, *, embedder=None, **backend_kwargs)

Connect to a vector database backend and return its Client.

This is the single entry point of vd. Switching vector databases is a one-argument change here.

Parameters:

• backend (str) – Backend name: "memory", "chroma", "qdrant", "faiss", "lancedb", "sqlite_vec", "duckdb", "pgvector", "pinecone", … Run vd.list_backends() for what is installed.

• embedder (Optional[Callable[[str], list[float]]]) – A text -> vector function. Supply it only if you want the convenience of passing raw text to collection[key] = "text" and collection.search("query text"). vd never embeds on its own — with no embedder, pass Document objects with vectors and pre-computed query vectors.

• **backend_kwargs – Backend-specific connection options (persist_directory, url, api_key, path, …). See each adapter’s docstring.

Returns:

A connected client — a Mapping of collection name to collection.

Return type:

Client

Examples

>>> client = connect('memory')
>>> client = connect('chroma', persist_directory='./db')
>>> client = connect('qdrant', url='http://localhost:6333')

vd.util.cosine_similarity(vec1, vec2)

Cosine similarity of two vectors (1.0 identical, 0.0 orthogonal).

Return type:

float

Examples

>>> cosine_similarity([1.0, 0.0], [1.0, 0.0])
1.0
>>> cosine_similarity([1.0, 0.0], [0.0, 1.0])
0.0

vd.util.euclidean_distance(vec1, vec2)

Euclidean (L2) distance between two vectors.

Return type:

float

Examples

>>> euclidean_distance([1.0, 0.0], [1.0, 0.0])
0.0

vd.util.get_backend(name)

Return the adapter Client class registered under name.

Raises:

• BackendNotInstalledError – If name is a known backend whose client library is not installed.

• ValueError – If name is not a known backend at all.

Return type:

type

vd.util.id_and_score(result)

Egress: keep (id, score).

Return type:

tuple[str, float]

vd.util.id_only(result)

Egress: keep only the document id.

Return type:

str

vd.util.id_text_score(result)

Egress: keep (id, text, score).

Return type:

tuple[str, str, float]

vd.util.list_backends()

Return the names of all backends with a registered (importable) adapter.

Return type:

list[str]

vd.util.mean_vector(vectors)

Component-wise mean of a non-empty iterable of equal-length vectors.

Return type:

list[float]

Examples

>>> mean_vector([[0.0, 2.0], [2.0, 4.0]])
[1.0, 3.0]

vd.util.normalize_document_input(doc_input, *, auto_id=True)

Normalize a flexible document input to a Document.

Accepted shapes: a Document; a str (just text); a tuple (text, id), (text, metadata), or (text, id, metadata).

Parameters:

• doc_input (Union[str, tuple, Document]) – The input to normalize.

• auto_id (bool) – When the input carries no id, generate one (vs. leaving it empty).

Return type:

Document

Examples

>>> normalize_document_input(("Hello", "doc1")).id
'doc1'
>>> normalize_document_input(("Hello", {"k": "v"})).metadata
{'k': 'v'}
>>> normalize_document_input("Hello world").id.startswith('doc_')
True

vd.util.register_backend(name)

Class decorator: register an adapter Client under name.

Return type:

Callable[[type], type]

Examples

>>> from vd.base import AbstractClient
>>> @register_backend('example')
... class ExampleClient(AbstractClient):
...     ...

vd.util.text_only(result)

Egress: keep only the text. >>> text_only({'text': 'hi'}) -> 'hi'.

Return type:

str