Vector Store Module

Vector storage backends for semantic search and retrieval

Vector Store Module

The vector store module provides a protocol-based system for storing and querying document embeddings.

Quick Start

from praisonaiagents.knowledge.vector_store import (
    VectorRecord,
    VectorStoreProtocol,
    VectorStoreRegistry,
    get_vector_store_registry,
    InMemoryVectorStore
)

# Use built-in in-memory store (no external deps)
store = InMemoryVectorStore()

# Add documents with embeddings
ids = store.add(
    texts=["Python is great", "Java is different"],
    embeddings=[[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]],
    metadatas=[{"lang": "python"}, {"lang": "java"}]
)

# Query by embedding
results = store.query(
    embedding=[0.1, 0.2, 0.3],
    top_k=5
)

for record in results:
    print(f"{record.text} (score: {record.score})")

Classes

VectorRecord

Dataclass representing a stored vector record.

@dataclass
class VectorRecord:
    id: str
    text: str
    embedding: List[float]
    metadata: Dict[str, Any] = field(default_factory=dict)
    score: Optional[float] = None

VectorStoreProtocol

Protocol defining the interface for vector stores.

class VectorStoreProtocol(Protocol):
    name: str
    
    def add(
        self,
        texts: List[str],
        embeddings: List[List[float]],
        metadatas: Optional[List[Dict[str, Any]]] = None,
        ids: Optional[List[str]] = None
    ) -> List[str]:
        """Add documents with embeddings."""
        ...
    
    def query(
        self,
        embedding: List[float],
        top_k: int = 10,
        filter: Optional[Dict[str, Any]] = None
    ) -> List[VectorRecord]:
        """Query by embedding vector."""
        ...
    
    def delete(self, ids: List[str]) -> None:
        """Delete records by ID."""
        ...
    
    def clear(self) -> None:
        """Clear all records."""
        ...

InMemoryVectorStore

Built-in vector store using cosine similarity (no external dependencies).

from praisonaiagents.knowledge.vector_store import InMemoryVectorStore

store = InMemoryVectorStore()

# Add documents
store.add(
    texts=["Hello world", "Goodbye world"],
    embeddings=[[1, 0, 0], [0, 1, 0]]
)

# Query
results = store.query([1, 0, 0], top_k=1)
print(results[0].text)  # "Hello world"

VectorStoreRegistry

Registry for managing vector store implementations.

from praisonaiagents.knowledge.vector_store import get_vector_store_registry

registry = get_vector_store_registry()

# List available stores
stores = registry.list_stores()  # ['memory', 'chroma', ...]

# Get store by name
store = registry.get("memory")

# Register custom store
registry.register("custom", MyCustomStore)

Supported Backends

Provider	Name	Install
In-Memory	memory	Built-in
ChromaDB	chroma	pip install chromadb
Pinecone	pinecone	pip install pinecone-client
Qdrant	qdrant	pip install qdrant-client
Weaviate	weaviate	pip install weaviate-client

Creating Custom Vector Stores

from praisonaiagents.knowledge.vector_store import (
    VectorRecord,
    get_vector_store_registry
)
from typing import List, Dict, Any, Optional

class MyVectorStore:
    name = "my_store"
    
    def __init__(self, **config):
        self.records = {}
    
    def add(
        self,
        texts: List[str],
        embeddings: List[List[float]],
        metadatas: Optional[List[Dict[str, Any]]] = None,
        ids: Optional[List[str]] = None
    ) -> List[str]:
        # Implementation
        ...
    
    def query(
        self,
        embedding: List[float],
        top_k: int = 10,
        filter: Optional[Dict[str, Any]] = None
    ) -> List[VectorRecord]:
        # Implementation
        ...

# Register
registry = get_vector_store_registry()
registry.register("my_store", MyVectorStore)

Performance

• InMemoryVectorStore requires no external dependencies
• Heavy backends (chromadb, etc.) are lazy-loaded only when accessed
• Zero import overhead when not using external stores