chromaroute

Provider-agnostic embedding functions for ChromaDB with automatic fallback support.

Features

• ChromaDB-native interface: Drop-in EmbeddingFunction implementations
• Provider fallback chain: OpenRouter → Local (SentenceTransformers)
• OpenRouter integration: Full support for OpenRouter's embedding API with provider routing
• Production-ready: Comprehensive error handling, configurable timeouts, actionable error messages

Installation

pip install chromaroute

# With local embeddings (SentenceTransformers)
pip install chromaroute[local]

Quick Start

from chromaroute import build_embedding_function, load_config

# Auto-detect available providers
config = load_config()
embed_fn = build_embedding_function(config)

# Or rely on environment auto-detection
embed_fn = build_embedding_function()

# Use with ChromaDB
import chromadb
client = chromadb.EphemeralClient()
collection = client.create_collection(
    name="my_collection",
    embedding_function=embed_fn,
)
collection.add(documents=["Hello world"], ids=["doc1"])

Configuration

Set environment variables:

# OpenRouter (primary)
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_EMBEDDINGS_MODEL=openai/text-embedding-3-small
OPENROUTER_EMBED_PROVIDER_JSON='{"order":["openai","mistral"],"allow_fallbacks":true}'

# Local fallback uses sentence-transformers/all-MiniLM-L6-v2 by default

Direct OpenRouter Usage

from chromaroute import OpenRouterEmbeddingFunction

embed_fn = OpenRouterEmbeddingFunction(
    model="openai/text-embedding-3-small",
    api_key="sk-or-...",
)

# Use with ChromaDB
embeddings = embed_fn(["text to embed"])
# Returns list[list[float]] with one embedding per input text.

VectorStore (Optional)

For simplified collection management with automatic batching:

from chromaroute import VectorStore

store = VectorStore("my_docs", persist_path="./chroma_db")
store.add_documents(
    documents=["Hello world", "Goodbye world"],
    metadatas=[{"source_id": "doc_a"}, {"source_id": "doc_b"}],
)

# Flat single-query result (lists per field)
result = store.query(
    query_texts="greeting",  # Accepts string or list[str]
    n_results=2,
    include=["documents", "metadatas", "distances"],
)
# Access first (and only) query's rows from nested results
top_docs = result["documents"][0]

# Row-like convenience result
records = store.query_one_records(
    "greeting",
    n_results=2,
    where={"source_id": "doc_a"},  # Filter by metadata
    include=["documents", "metadatas", "distances"],
)

query()/get() pass include, where, and where_document directly to ChromaDB. If include is omitted, ChromaDB defaults are used.

Common Recipes

1. Provenance-aware retrieval: Store source_id in metadata during ingest and include "metadatas" at query time. Filter by it using where={"source_id": "..."}.
2. Application-ready rows: Use query_one_records() when you want id/document/distance/metadata bundled into one object per hit.
3. Stale data removal: Use store.delete(where={"source_id": "..."}) before re-ingesting a previously processed document source to prevent duplicates.
4. Advanced ChromaDB features: For partial updates or upserts, use the underlying Chroma collection directly via store.collection.

Environment Variables

Advanced Usage (Best-Effort)

chromaroute is optimized for OpenRouter, but includes a few intentional escape hatches for custom setups. These are not the primary path and are supported on a best-effort basis. See docs/advanced.md.

License

MIT