localvectordb.factory module

Enhanced Factory function for LocalVectorDB v1.0 with Async Support

This module provides factory functions that automatically choose between local and remote database implementations, with support for both sync and async variants.

localvectordb.factory.VectorDB(name: str, base_path: str | Path, **kwargs) → LocalVectorDB | RemoteVectorDB

Enhanced factory function that returns the appropriate VectorDB instance based on whether base_path looks like a URL or a local path, with optional async support.

This factory automatically handles the differences between local and remote implementations, and between sync and async variants, making it easy to switch between them.

Parameters:

name (str) – Name of the database
base_path (Union[str, Path]) – Path or URL to the database. If it starts with ‘http://’ or ‘https://’, a RemoteVectorDB will be created. Otherwise, a LocalVectorDB will be created.
**kwargs (dict) –
Additional arguments to pass to the appropriate constructor.

These include: - metadata_schema: Dict[str, MetadataField] - Schema for metadata fields - embedding_provider: str - Provider for embeddings (“ollama”, “openai”) - embedding_model: str - Model name for embeddings - embedding_config: Dict[str, Any] - Config for embedding provider - chunking_method: str - Method for chunking (“sentences”, “tokens”, etc.) - chunk_size: int - Maximum tokens per chunk - chunk_overlap: int - Overlap in the method’s own unit, not tokens (except “tokens”); keep small (1-3) - enable_gpu: bool - Whether to use GPU for FAISS - enable_fts: bool - Whether to enable full-text search - create_if_not_exists: bool - Whether to create if not exists

For RemoteVectorDB, these include: - api_key: str - API key for authentication - request_timeout: int - Timeout for HTTP requests - max_retries: int - Number of retry attempts - retry_delay: float - Base delay between retries - connection_pool_limits: httpx.Limits - HTTP connection pool settings

Returns:

An instance of the appropriate vector database class

Return type:

Union[LocalVectorDB, RemoteVectorDB]

Examples

Sync local database:

from localvectordb import VectorDB
from localvectordb.core import MetadataField, MetadataFieldType

# Create a sync local database
db = VectorDB(
    "my_docs",
    "./vector_storage",
    metadata_schema={
        'author': MetadataField(type=MetadataFieldType.TEXT, indexed=True),
        'date': MetadataField(type=MetadataFieldType.DATE, indexed=True)
    },
    embedding_model="nomic-embed-text",
    chunk_size=500
)

Sync remote database:

# Create a sync remote database connection
db = VectorDB(
    "my_docs",
    "http://localhost:5000",
    api_key="your_api_key",
    metadata_schema={
        'author': MetadataField(type=MetadataFieldType.TEXT, indexed=True),
        'date': MetadataField(type=MetadataFieldType.DATE, indexed=True)
    }
)

# Async built in
async with db as async_db:
    doc_ids = await async_db.upsert_async(["Document 1", "Document 2"])

Notes

The factory function automatically filters out incompatible parameters for each implementation
Local databases require appropriate dependencies (FAISS, SQLite)
Remote databases require a running LocalVectorDB server

Raises:

ImportError – If required dependencies are not available for the chosen implementation
ValueError – If invalid parameters are provided for the chosen implementation

localvectordb.factory.from_uri(db_uri: str) → LocalVectorDB | RemoteVectorDB