refinire-rag-chroma
ChromaDB VectorStore plugin for refinire-rag, providing seamless integration with ChromaDB for vector storage and similarity search.
Features
- ✅ Zero Configuration: Works out of the box with sensible defaults
- ✅ Environment Variable Configuration: Configure via
REFINIRE_RAG_CHROMA_*environment variables - ✅ Full refinire-rag v0.1.1+ Compatibility: Implements the complete VectorStore interface
- ✅ DocumentProcessor Integration: Supports refinire-rag processing pipelines
- ✅ Persistent and In-Memory Storage: Choose between persistent disk storage or in-memory
- ✅ Multiple Distance Metrics: Support for cosine, L2, and inner product distance
- ✅ Production Ready: Comprehensive error handling, logging, and validation
Quick Start
Zero Configuration Usage
from refinire_rag_chroma import ChromaVectorStore
# Works immediately with default settings
vector_store = ChromaVectorStore()
# Add documents (requires embedder)
vector_store.set_embedder(your_embedder)
processed_docs = list(vector_store.process(documents))
Environment Variable Configuration
# Set environment variables
export REFINIRE_RAG_CHROMA_COLLECTION_NAME="my_documents"
export REFINIRE_RAG_CHROMA_PERSIST_DIRECTORY="/data/chroma"
export REFINIRE_RAG_CHROMA_DISTANCE_METRIC="cosine"
from refinire_rag_chroma import ChromaVectorStore
# Automatically uses environment variables
vector_store = ChromaVectorStore()
Installation
pip install refinire-rag-chroma
Or with uv:
uv add refinire-rag-chroma
Configuration
Environment Variables
| Variable | Default | Description |
|---|---|---|
REFINIRE_RAG_CHROMA_COLLECTION_NAME |
"refinire_documents" |
Collection name |
REFINIRE_RAG_CHROMA_PERSIST_DIRECTORY |
None |
Storage directory (None = in-memory) |
REFINIRE_RAG_CHROMA_DISTANCE_METRIC |
"cosine" |
Distance metric ("cosine", "l2", "ip") |
REFINIRE_RAG_CHROMA_BATCH_SIZE |
100 |
Batch size for operations |
REFINIRE_RAG_CHROMA_MAX_RETRIES |
3 |
Maximum retry attempts |
REFINIRE_RAG_CHROMA_AUTO_CREATE_COLLECTION |
"true" |
Auto-create collection |
REFINIRE_RAG_CHROMA_AUTO_CLEAR_ON_INIT |
"false" |
Clear on initialization |
Parameter-based Configuration
from refinire_rag_chroma import ChromaVectorStore
# Override specific settings with parameters
vector_store = ChromaVectorStore(
collection_name="custom_collection",
persist_directory="/path/to/storage",
distance_metric="l2"
)
Usage Examples
Basic Vector Operations
import numpy as np
from refinire_rag_chroma import ChromaVectorStore
from refinire_rag.storage import VectorEntry
vector_store = ChromaVectorStore()
# Add a vector
entry = VectorEntry(
document_id="doc1",
content="Sample document",
embedding=np.array([0.1, 0.2, 0.3, 0.4, 0.5]),
metadata={"source": "example"}
)
vector_store.add_vector(entry)
# Search similar vectors
query_vector = np.array([0.1, 0.2, 0.3, 0.4, 0.5])
results = vector_store.search_similar(query_vector, limit=10)
Document Processing Pipeline
from refinire_rag_chroma import ChromaVectorStore
from refinire_rag.models.document import Document
# Set up vector store with embedder
vector_store = ChromaVectorStore()
vector_store.set_embedder(your_embedder)
# Process documents
documents = [
Document(id="1", content="First document", metadata={}),
Document(id="2", content="Second document", metadata={})
]
# Documents are automatically embedded and stored
processed_docs = list(vector_store.process(documents))
Metadata Filtering
# Search by metadata
results = vector_store.search_by_metadata(
filters={"source": "wikipedia"},
limit=50
)
# Count vectors with filters
count = vector_store.count_vectors(filters={"category": "science"})
Docker Usage
FROM python:3.10
ENV REFINIRE_RAG_CHROMA_COLLECTION_NAME=production_docs
ENV REFINIRE_RAG_CHROMA_PERSIST_DIRECTORY=/data/chroma
ENV REFINIRE_RAG_CHROMA_DISTANCE_METRIC=cosine
COPY . /app
WORKDIR /app
RUN pip install refinire-rag-chroma
CMD ["python", "app.py"]
Docker Compose
version: '3.8'
services:
app:
image: my-app:latest
environment:
- REFINIRE_RAG_CHROMA_COLLECTION_NAME=production_docs
- REFINIRE_RAG_CHROMA_PERSIST_DIRECTORY=/data/chroma
- REFINIRE_RAG_CHROMA_BATCH_SIZE=200
volumes:
- chroma_data:/data/chroma
volumes:
chroma_data:
API Reference
ChromaVectorStore
The main vector store implementation that supports both the VectorStore and DocumentProcessor interfaces.
Methods
add_vector(entry: VectorEntry) -> str: Add a single vectoradd_vectors(entries: List[VectorEntry]) -> List[str]: Add multiple vectorsget_vector(document_id: str) -> Optional[VectorEntry]: Retrieve a vectorupdate_vector(entry: VectorEntry) -> bool: Update a vectordelete_vector(document_id: str) -> bool: Delete a vectorsearch_similar(query_vector: np.ndarray, limit: int, threshold: Optional[float], filters: Optional[Dict]) -> List[VectorSearchResult]: Search similar vectorssearch_by_metadata(filters: Dict, limit: int) -> List[VectorSearchResult]: Search by metadata onlycount_vectors(filters: Optional[Dict]) -> int: Count vectorsget_stats() -> VectorStoreStats: Get store statisticsclear() -> bool: Clear all vectorsset_embedder(embedder: Any) -> None: Set embedder for processingprocess(documents: Iterable[Document], config: Optional[Any]) -> Iterator[Document]: Process documents
Configuration
ChromaVectorStore automatically reads configuration from environment variables with sensible defaults. You can override specific settings by passing parameters to the constructor.
Development
Setup
git clone https://github.com/your-repo/refinire-rag-chroma
cd refinire-rag-chroma
uv install
Testing
uv run pytest
With Coverage
uv run pytest --cov=src
Requirements
- Python 3.8+
- refinire-rag >=0.1.1
- chromadb >=0.4.0
- numpy
License
MIT License - see LICENSE file for details.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Run tests and ensure they pass
- Submit a pull request
Changelog
v0.0.1
- Initial release
- Full refinire-rag v0.1.1+ compatibility
- Environment variable configuration system
- Zero-configuration deployment support
- DocumentProcessor integration
- Comprehensive test suite
Metadata
Release files for refinire-rag-chroma 0.0.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| refinire_rag_chroma-0.0.6.tar.gz | 13.4 kB | Without provenance | Details for refinire_rag_chroma-0.0.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| refinire_rag_chroma-0.0.6-py3-none-any.whl | Python 3 | none | any | Details for refinire_rag_chroma-0.0.6-py3-none-any.whl |
Total release size: 25.8 kB
Release files / refinire_rag_chroma-0.0.6.tar.gz
| Download URL | refinire_rag_chroma-0.0.6.tar.gz |
|---|---|
| Size | 13.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
74ced162c57aa2b2746c6d54aad6180ceb65adf8ceebf5c623b3a9661940901b
|
|
BLAKE2b-256 checksum How to use checksums |
c106fadab354f0d6d173513eb5d0b0e6b1d04055e36a88c8bd833943aab4396c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.12
|
Release files / refinire_rag_chroma-0.0.6-py3-none-any.whl
| Download URL | refinire_rag_chroma-0.0.6-py3-none-any.whl |
|---|---|
| Size | 12.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
75a2b3d2d422c2670c98203649ed79f13240776d891a21ce704f289962d94c88
|
|
BLAKE2b-256 checksum How to use checksums |
3de7a44f6f35ade0faa7bbe8b99f3df9c4cab41e8e899b543026cfc859979480
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.12
|
Security for refinire-rag-chroma 0.0.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.