# How to Integrate Turbovec with LangChain for Vector Storage

> Integrate Turbovec with LangChain for persistent, quantized vector storage. Replace in-memory stores easily with TurboQuantVectorStore without code changes. Boost performance and scalability.

- Repository: [Ryan Codrai/turbovec](https://github.com/RyanCodrai/turbovec)
- Tags: how-to-guide
- Published: 2026-08-22

---

**Turbovec provides a drop-in LangChain integration through `TurboQuantVectorStore`, allowing you to replace in-memory vector stores with a quantized, persistent backend without modifying existing LangChain code.**

Integrating **Turbovec** with **LangChain for vector storage** gives you a high-performance, quantized alternative to in-memory stores. The `TurboQuantVectorStore` class in `RyanCodrai/turbovec`'s [`turbovec-python/python/turbovec/langchain.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/langchain.py) implements LangChain's `VectorStore` API, mirroring the interface of `InMemoryVectorStore` while adding binary persistence and configurable quantization. This guide shows you how to install, configure, and deploy Turbovec within any LangChain application.

## Installation and Setup

### Installing the LangChain Extra

To access the LangChain integration, install Turbovec with the optional LangChain dependencies. This ensures compatibility with `langchain_core` interfaces.

```bash
pip install "turbovec[langchain]"

```

### Embedding Model Requirements

`TurboQuantVectorStore` requires any object implementing `langchain_core.embeddings.Embeddings`. This includes OpenAI, HuggingFace, or custom embedding providers. The store uses this model to convert texts into vectors before quantization.

## Creating a TurboQuantVectorStore Instance

### Basic Initialization

Instantiate the store by passing an embeddings object and optional configuration parameters. According to [`turbovec-python/python/turbovec/langchain.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/langchain.py), the `bit_width` parameter controls quantization precision (2–4 bits per dimension), while `similarity` selects the distance metric.

```python
from turbovec.langchain import TurboQuantVectorStore

store = TurboQuantVectorStore(
    embedding=my_embedding,   # Embeddings instance

    bit_width=4,             # 2-4 bits per dimension (default 4)

    similarity="cosine",     # "cosine" (default) or "dot_product"

)

```

### Using Class Methods for Quick Setup

For rapid prototyping, use the `from_texts` class method to create and populate a store in one call. This initializes the underlying `IdMapIndex` from [`turbovec-python/python/turbovec/_turbovec.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/_turbovec.py) and adds documents simultaneously.

```python
store = TurboQuantVectorStore.from_texts(
    ["turbovec is fast", "turbovec uses quantization"],
    my_embedding,
    metadatas=[{"tag": "intro"}, {"tag": "tech"}],
    bit_width=4
)

```

## Adding and Searching Documents

### Adding Texts with Metadata

Add documents using `add_texts()` with optional metadata dictionaries and custom IDs. The method returns the list of IDs assigned to the stored vectors.

```python
ids = store.add_texts(
    ["first paragraph", "second paragraph"],
    metadatas=[{"source": "doc1"}, {"source": "doc2"}],
    ids=["doc-1", "doc-2"]
)

```

### Similarity Search Operations

The store implements standard LangChain search methods. `similarity_search()` returns `Document` objects, while `similarity_search_with_score()` includes distance metrics.

```python

# Standard search

results = store.similarity_search("query text", k=4)

# Search with scores

scored = store.similarity_search_with_score("query", k=4)

# Search by pre-computed vector

by_vec = store.similarity_search_by_vector([0.1, 0.2, ...], k=4)

```

### Filtering Results

Apply metadata filters using dictionaries or callables. The `filter` parameter works across all search variants, as demonstrated in [`turbovec-python/tests/test_langchain.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/tests/test_langchain.py).

```python
filtered = store.similarity_search(
    "important query", 
    k=4, 
    filter={"tag": "important"}
)

```

## Persistence and Serialization

### Saving the Index

Turbovec writes a binary index (`index.tvim`) and a JSON sidecar ([`docstore.json`](https://github.com/RyanCodrai/turbovec/blob/main/docstore.json)) containing metadata and text. The `dump()` method in [`turbovec-python/python/turbovec/_persist.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/_persist.py) handles atomic serialization.

```python
store.dump("/path/to/store_folder")

```

### Loading from Disk

Reload a persisted store using `load()`, passing the folder path and the embedding model. The embedding instance must match the dimensionality of the saved index.

```python
loaded = TurboQuantVectorStore.load("/path/to/store_folder", my_embedding)

```

## Integration with LangChain Chains

### Using as a Retriever

The `as_retriever()` method returns a LangChain-compatible retriever for use in chains or agents. Configure search parameters through `search_kwargs`.

```python
retriever = store.as_retriever(
    search_kwargs={"k": 5, "filter": {"tag": "keep"}}
)
docs = retriever.invoke("what is turbovec?")

```

### Async Operations Support

All core operations provide async equivalents for non-blocking I/O. Use `afrom_texts()`, `aadd_texts()`, and `asimilarity_search()` in async applications.

```python
ids = await store.aadd_texts(["async doc"])
async_results = await store.asimilarity_search("async query", k=3)

```

## Configuration Options

### Quantization Settings

The `bit_width` parameter controls the compression level implemented in [`turbovec-python/python/turbovec/_turbovec.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/_turbovec.py). Lower values reduce memory footprint but may decrease precision. Valid values are 2, 3, or 4 bits per dimension.

### Similarity Metrics

Configure distance calculation in [`turbovec-python/python/turbovec/_similarity.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/_similarity.py). Options include `"cosine"` (default, L2-normalized dot product) and `"dot_product"` (raw inner product).

## Summary

- **Install** Turbovec with LangChain support using `pip install "turbovec[langchain]"`.
- **Initialize** `TurboQuantVectorStore` with an `Embeddings` instance and optional `bit_width` (2-4) and `similarity` settings.
- **Add documents** via `add_texts()` or `from_texts()`, supporting metadata and custom IDs.
- **Search** using standard LangChain methods like `similarity_search()`, with optional filtering and score retrieval.
- **Persist** data using `dump()` and `load()` via [`turbovec-python/python/turbovec/_persist.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/_persist.py) to maintain indices between sessions.
- **Integrate** seamlessly into chains using `as_retriever()` or operate asynchronously with `aadd_texts()` and `asimilarity_search()`.

## Frequently Asked Questions

### What embedding models work with Turbovec's LangChain integration?

Any object implementing the `langchain_core.embeddings.Embeddings` interface works, including OpenAI, HuggingFace, sentence-transformers, or custom implementations. The embedding dimensionality determines the index structure quantized by [`turbovec-python/python/turbovec/_turbovec.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/_turbovec.py).

### How does TurboQuantVectorStore handle persistence?

The store serializes quantized vectors to a binary `index.tvim` file and document metadata to a [`docstore.json`](https://github.com/RyanCodrai/turbovec/blob/main/docstore.json) sidecar. Use `dump()` to save and `load()` to restore, ensuring you provide the same embedding model during reconstruction.

### Can I filter documents during similarity searches?

Yes. Pass a dictionary to the `filter` parameter (e.g., `{"category": "tutorial"}`) or use a callable for complex logic. Filtering works in `similarity_search()`, `similarity_search_with_score()`, and retriever configurations.

### Is async supported for all vector operations?

Yes. `TurboQuantVectorStore` provides async variants for all mutating and querying operations, including `aadd_texts()`, `asimilarity_search()`, and the `afrom_texts()` constructor, enabling non-blocking vector storage in async applications.