ovos-chromadb-embeddings-plugin

ChromaDB-backed EmbeddingsDB vector store plugin for OpenVoiceOS.

Install

pip install ovos-chromadb-embeddings-plugin

What is an EmbeddingsDB?

EmbeddingsDB is the abstract base class from ovos-plugin-manager for vector stores. Plugins implementing it are discovered automatically by OPM under the entry-point group opm.embeddings. This plugin registers as:

opm.embeddings → ovos-chromadb-embeddings-plugin → ChromaEmbeddingsDB

OVOS subsystems call OVOSPluginFactory.get_plugin("opm.embeddings") to obtain a configured store without coupling to a specific backend, so any EmbeddingsDB plugin (ChromaDB here, or e.g. qdrant) is a drop-in swap.

Where this fits in OVOS

This plugin is the vector store half of the stack. It stores and searches vectors but does not produce them. Pair it with an embedding producer such as ovos-gguf-embeddings-plugin (text → vectors), or the face / voice embedders.

Concrete consumers that can be backed by this store:

It is local-first: in persistent mode it runs fully offline on a CPU with no server.

Quickstart

import tempfile, numpy as np
from ovos_chromadb_embeddings import ChromaEmbeddingsDB

with tempfile.TemporaryDirectory() as tmp:
    db = ChromaEmbeddingsDB(config={"path": tmp})

    # Store a few 4-d vectors
    db.add_embeddings("apple",  np.array([0.9, 0.1, 0.0, 0.0]))
    db.add_embeddings("banana", np.array([0.0, 0.9, 0.1, 0.0]))
    db.add_embeddings("cherry", np.array([0.0, 0.0, 0.9, 0.1]))

    # Nearest-neighbour query
    query = np.array([0.85, 0.15, 0.0, 0.0])
    results = db.query(query, top_k=2)
    # → [("apple", 0.003...), ("banana", 0.45...)]
    print(results[0][0])  # "apple"

query returns (id, distance) tuples ordered nearest-first. The score is a distance, not a similarity. Lower is closer for the default cosine metric (and for l2). Change the metric with hnsw:space (see Configuration). The query vector must have the same dimensionality as the stored vectors.

Configuration

Pass a config dict to ChromaEmbeddingsDB(config=...) or set it in your OVOS configuration under the plugin key.

Local (persistent) mode

db = ChromaEmbeddingsDB(config={"path": "/var/lib/ovos/chromadb"})

Remote server mode

db = ChromaEmbeddingsDB(config={"host": "192.168.1.10", "port": 8000})

API overview

Documentation

• docs/configuration.md: full config reference (local vs remote, distance metrics)
• docs/usage.md: collections, CRUD, batch ops, metadata, numpy in/out

Examples

• examples/quickstart.py: add vectors + query
• examples/collections.py: multi-collection workflow
• examples/remote_server.py: HttpClient usage

Testing

pip install -e ".[test]"
pytest test/ -v

The test suite uses a temporary PersistentClient with no network access. test/test_e2e.py runs a real end-to-end flow (add → query → verify nearest neighbour) using a small deterministic local embedder so it passes in CI without model downloads.

Credits

TigreGótico originally developed this plugin for OpenVoiceOS, sponsored by VisioLab. The NGI0 Commons Fund / NLnet funded the modernization.

This work was sponsored by VisioLab, part of Royal Dutch Visio. Royal Dutch Visio is the test, education, and research center in the field of (innovative) assistive technology for blind and visually impaired people and professionals. We explore (new) technological developments such as Voice, VR and AI and make the knowledge and expertise we gain available to everyone.

This project was funded through the NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101135429.