> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
@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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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).

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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