Architecture

re-exports five names, which together form the package's public API surface:

Class hierarchy

* marks @abstractmethods that every subclass must implement. Everything else on VectorDatabaseBase has a default implementation that subclasses may override (and each concrete backend overrides most of them).

Initialization flow (example: FAISS)

All three backends follow the same general shape: call super().__init__(embedder), validate configuration, resolve the embedding dimension, then stand up the backend's underlying client or index. Chroma additionally creates or retrieves a named collection (_initialize_client → _initialize_collection), and Pinecone additionally creates or verifies a remote index and blocks until it's ready (_initialize_pinecone → _create_index/_verify_index_config → _wait_for_index_ready).

Search flow (unified shape)

All three search() implementations converge on the same return type, List[Tuple[DocumentChunk, float]], which is the basis for calling them interchangeably. Note per-backend differences documented on each class's reference page — for example, only FAISS and Pinecone accept a doc_id_filter/filter_dict argument with that exact name; Chroma's equivalent parameter is filters.

Metadata sanitization

sanitize_metadata() (in base.py) is the single place where metadata is made safe across all three backends, since ChromaDB rejects None and list values outright:

FAISSVectorDatabase.add() and PineconeVectorDatabase.add() call sanitize_metadata() directly on each chunk's metadata. ChromaVectorDatabase.add() calls it on both the DocumentChunk-list path and the legacy path.

External dependencies

DocumentChunk

DocumentChunk is not defined anywhere in the analyzed archive. It's imported:

• In chroma.py and pinecone.py: from ..chunks import DocumentChunk — a hard dependency on a sibling package that must exist in the parent project.
• In base.py: a three-step fallback —
  1. try from chunks.doc_model import DocumentChunk
  2. try from ..chunks.doc_model import DocumentChunk
  3. otherwise, define a local fallback dataclass so base.py can be imported standalone.

The fallback dataclass, which is the only concrete definition of DocumentChunk visible in this codebase, is:

@dataclass
class DocumentChunk:
    chunk_id: str
    doc_id: str
    text: str
    embedding: Optional[np.ndarray] = None
    metadata: Dict = field(default_factory=dict)

    def __post_init__(self):
        if not self.chunk_id or not self.doc_id:
            raise ValueError("chunk_id and doc_id are required")
        if not self.text or not self.text.strip():
            raise ValueError("text cannot be empty")

    @property
    def id(self):
        return self.chunk_id

Because faiss, chroma, and pinecone import DocumentChunk from ..chunks directly (no fallback), this local dataclass is not guaranteed to be the same class those three modules actually use at runtime — it's only confirmed to be what base.py falls back to when imported in isolation. Treat the field list above as a reliable shape reference, not a guaranteed identical class.

RAGSystem

base.py's docstrings reference a RAGSystem orchestrator ("RAGSystem only calls the five mandatory methods...") that is not present in the analyzed archive. Its existence and exact behavior cannot be verified from this codebase — treat mentions of it in this documentation as context taken directly from source comments, not as documented, verified behavior.

Third-party libraries

This means importing vector_database itself never fails due to a missing backend dependency — only instantiating the corresponding class does.

Next steps

See the API Reference for exhaustive per-class documentation.