tessl/pypi-chromadb

Chroma - the open-source embedding database

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Configuration

Name: tessl/pypi-chromadb
Author: tessl

ChromaDB provides a comprehensive configuration system for customizing behavior across authentication, server settings, storage, telemetry, and system components. Configuration can be set through environment variables, initialization parameters, or the global configure function.

Capabilities

Global Configuration

Set global configuration options that apply to all ChromaDB clients and operations.

def configure(**kwargs) -> None:
    """
    Override Chroma's default settings, environment variables or .env files.
    
    Args:
        **kwargs: Configuration options as key-value pairs
    """

def get_settings() -> Settings:
    """
    Get the current global settings.
    
    Returns:
        Settings: Current configuration settings object
    """

Usage Examples:

import chromadb

# Configure global settings
chromadb.configure(
    chroma_api_impl="chromadb.api.fastapi.FastAPI",
    chroma_server_host="localhost",
    chroma_server_http_port=8000,
    persist_directory="/path/to/data"
)

# Get current settings
settings = chromadb.get_settings()
print(f"Server host: {settings.chroma_server_host}")
print(f"Persist directory: {settings.persist_directory}")

Settings Class

The Settings class provides comprehensive configuration options for all aspects of ChromaDB operation.

class Settings:
    """ChromaDB configuration settings."""
    
    def __init__(self, **kwargs):
        """
        Initialize settings with configuration options.
        
        Common configuration options:
        
        # API Implementation
        chroma_api_impl: str = "chromadb.api.segment.SegmentAPI"
        
        # Server Configuration  
        chroma_server_host: str = "localhost"
        chroma_server_http_port: int = 8000
        chroma_server_ssl_enabled: bool = False
        chroma_server_headers: Optional[Dict[str, str]] = None
        
        # Storage Configuration
        persist_directory: Optional[str] = None
        is_persistent: bool = False
        allow_reset: bool = False
        
        # Authentication
        chroma_client_auth_provider: Optional[str] = None
        chroma_client_auth_credentials: Optional[str] = None
        chroma_auth_token_transport_header: Optional[str] = None
        
        # Telemetry
        anonymized_telemetry: bool = True
        
        # Performance
        chroma_segment_cache_policy: str = "LRU"
        chroma_segment_cache_max_size_bytes: int = 1024 * 1024 * 1024  # 1GB
        
        # System Components
        chroma_collection_assignment_policy: str = "chromadb.ingest.impl.simple.SimpleAssignmentPolicy"
        
        Args:
            **kwargs: Configuration key-value pairs
        """

API Implementation Configuration

Configure which ChromaDB API implementation to use for different deployment scenarios.

Configuration Options:

# Local segment-based API (default)
chroma_api_impl = "chromadb.api.segment.SegmentAPI"

# FastAPI server implementation
chroma_api_impl = "chromadb.api.fastapi.FastAPI"

# Async FastAPI implementation
chroma_api_impl = "chromadb.api.async_fastapi.AsyncFastAPI"

# Rust-backed implementation
chroma_api_impl = "chromadb.api.rust.RustBindingsAPI"

Usage Examples:

from chromadb.config import Settings

# Configure for local persistent storage
settings = Settings(
    chroma_api_impl="chromadb.api.segment.SegmentAPI",
    persist_directory="/data/chromadb",
    is_persistent=True
)

client = chromadb.Client(settings=settings)

Server Configuration

Configure connection parameters for remote ChromaDB servers.

# Server connection settings
chroma_server_host: str = "localhost"
chroma_server_http_port: int = 8000
chroma_server_ssl_enabled: bool = False
chroma_server_headers: Optional[Dict[str, str]] = None

Usage Examples:

# Configure for remote server with SSL
settings = Settings(
    chroma_api_impl="chromadb.api.fastapi.FastAPI",
    chroma_server_host="chroma.example.com",
    chroma_server_http_port=443,
    chroma_server_ssl_enabled=True,
    chroma_server_headers={
        "Authorization": "Bearer your-token",
        "Custom-Header": "custom-value"
    }
)

client = chromadb.Client(settings=settings)

Storage Configuration

Configure data persistence and storage behavior.

# Storage settings
persist_directory: Optional[str] = None  # Directory for persistent storage
is_persistent: bool = False              # Enable persistence
allow_reset: bool = False                # Allow database reset operations

Usage Examples:

# Configure persistent storage
settings = Settings(
    persist_directory="/var/lib/chromadb",
    is_persistent=True,
    allow_reset=False  # Disable reset for safety
)

# Configure in-memory storage
settings = Settings(
    is_persistent=False,
    allow_reset=True  # Allow reset for testing
)

Authentication Configuration

Configure authentication providers and credentials for secure deployments.

# Authentication settings
chroma_client_auth_provider: Optional[str] = None
chroma_client_auth_credentials: Optional[str] = None
chroma_auth_token_transport_header: Optional[str] = None
chroma_overwrite_singleton_tenant_database_access_from_auth: bool = False

Usage Examples:

from chromadb.auth.token_authn import TokenTransportHeader

# Configure token authentication
settings = Settings(
    chroma_client_auth_provider="chromadb.auth.token_authn.TokenAuthClientProvider",
    chroma_client_auth_credentials="your-auth-token",
    chroma_auth_token_transport_header=TokenTransportHeader.X_CHROMA_TOKEN,
    chroma_overwrite_singleton_tenant_database_access_from_auth=True
)

client = chromadb.Client(settings=settings)

Telemetry Configuration

Configure telemetry and monitoring settings.

# Telemetry settings
anonymized_telemetry: bool = True
chroma_telemetry_impl: str = "chromadb.telemetry.posthog.Posthog"

Usage Examples:

# Disable telemetry
settings = Settings(anonymized_telemetry=False)

# Custom telemetry implementation
settings = Settings(
    chroma_telemetry_impl="your.custom.telemetry.Implementation"
)

Performance Configuration

Configure caching, batching, and performance-related settings.

# Performance settings
chroma_segment_cache_policy: str = "LRU"
chroma_segment_cache_max_size_bytes: int = 1024 * 1024 * 1024  # 1GB
chroma_collection_assignment_policy: str = "chromadb.ingest.impl.simple.SimpleAssignmentPolicy"

Environment Variables

ChromaDB settings can be configured through environment variables using the CHROMA_ prefix.

Common Environment Variables:

# Server configuration
export CHROMA_SERVER_HOST="localhost"
export CHROMA_SERVER_HTTP_PORT="8000"
export CHROMA_SERVER_SSL_ENABLED="false"

# Storage configuration
export CHROMA_PERSIST_DIRECTORY="/data/chromadb"
export CHROMA_IS_PERSISTENT="true"

# Authentication
export CHROMA_CLIENT_AUTH_PROVIDER="chromadb.auth.token_authn.TokenAuthClientProvider"
export CHROMA_CLIENT_AUTH_CREDENTIALS="your-token"

# Cloud client
export CHROMA_API_KEY="your-cloud-api-key"
export CHROMA_TENANT="your-tenant"
export CHROMA_DATABASE="your-database"

# Telemetry
export CHROMA_ANONYMIZED_TELEMETRY="false"

Multi-tenancy Configuration

Configure tenant and database settings for multi-tenant deployments.

# Default tenant and database constants
DEFAULT_TENANT: str = "default_tenant"
DEFAULT_DATABASE: str = "default_database"

Usage Examples:

# Create client with specific tenant/database
client = chromadb.Client(
    tenant="organization_a",
    database="production_db"
)

# Switch tenant/database on existing client
client.set_tenant("organization_b", database="staging_db")
client.set_database("development_db")

Component System Configuration

Configure the dependency injection system and component implementations.

class Component:
    """Base class for ChromaDB system components."""
    
class System:
    """Dependency injection system for ChromaDB components."""
    
    def instance(self, type_class: type) -> Any:
        """Get or create component instance."""
        
    def reset_state(self) -> None:
        """Reset system state."""

Types

from typing import Dict, Optional, Any, Union
from pathlib import Path

class Settings:
    """ChromaDB configuration settings class."""
    
    # API Implementation
    chroma_api_impl: str
    
    # Server Configuration
    chroma_server_host: str
    chroma_server_http_port: int
    chroma_server_ssl_enabled: bool
    chroma_server_headers: Optional[Dict[str, str]]
    
    # Storage Configuration
    persist_directory: Optional[Union[str, Path]]
    is_persistent: bool
    allow_reset: bool
    
    # Authentication
    chroma_client_auth_provider: Optional[str]
    chroma_client_auth_credentials: Optional[str]
    chroma_auth_token_transport_header: Optional[str]
    
    # Telemetry
    anonymized_telemetry: bool
    chroma_telemetry_impl: str
    
    # Performance
    chroma_segment_cache_policy: str
    chroma_segment_cache_max_size_bytes: int
    
    def __init__(self, **kwargs): ...

# Constants
DEFAULT_TENANT: str = "default_tenant"
DEFAULT_DATABASE: str = "default_database"

Install with Tessl CLI