# How to Integrate Turbovec with LangChain as a Vector Store: Complete Guide

> Integrate Turbovec with LangChain as a vector store effortlessly. Use TurboQuantVectorStore to replace InMemoryVectorStore with a quantized, persistent index without changing your chain code.

- Repository: [Ryan Codrai/turbovec](https://github.com/RyanCodrai/turbovec)
- Tags: tutorial
- Published: 2026-07-27

---

**Turbovec ships a drop-in `TurboQuantVectorStore` class that implements LangChain's `VectorStore` API, allowing you to replace `InMemoryVectorStore` with a quantized, persistent index without modifying downstream chain code.**

Integrating turbovec with LangChain as a vector store adds a high-performance, quantized retrieval backend to your LLM pipelines. The `TurboQuantVectorStore` class, defined in [`turbovec-python/python/turbovec/langchain.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/langchain.py), mirrors the public surface of `langchain_core.vectorstores.InMemoryVectorStore`. It delegates indexing to the Rust-backed `IdMapIndex` in [`turbovec-python/python/turbovec/_turbovec.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/_turbovec.py) and supports full persistence, async operations, and metadata filtering.

## Installation and Prerequisites

To begin, install turbovec with the LangChain extra. You also need any embedding model that implements the `langchain_core.embeddings.Embeddings` interface.

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

```

OpenAI, HuggingFace, or custom embeddings stubs all satisfy this contract.

## Initializing TurboQuantVectorStore

Create a store by passing an embeddings instance and optional quantization parameters.

```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"

)

```

The `similarity` argument is resolved by utilities in [`turbovec-python/python/turbovec/_similarity.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/_similarity.py), which handles `COSINE` and `DOT_PRODUCT` modes along with vector normalization. You can also instantiate directly from a corpus using `from_texts`:

```python
store = TurboQuantVectorStore.from_texts(
    ["a", "b", "c"], my_embedding, bit_width=4
)

```

## Adding Documents and Indexing Texts

The `add_texts` method accepts raw strings, optional metadata dictionaries, and explicit IDs, matching the standard LangChain `VectorStore` contract found in `InMemoryVectorStore`. This lets you index documents with full metadata tracking using the same interface defined by `langchain_core`.

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

```

### Async Ingestion

For async workloads, turbovec provides `aadd_texts` and `afrom_texts`. These async variants are fully implemented in [`turbovec-python/python/turbovec/langchain.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/langchain.py) and validated by the test suite in [`turbovec-python/tests/test_langchain.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/tests/test_langchain.py).

```python
ids = await store.aadd_texts(["more async"], ids=["new-id"])

```

## Similarity Search and Retrieval

`TurboQuantVectorStore` exposes the complete LangChain search surface. You can query by text, by pre-computed vector, with scores, or with metadata filters.

### Standard Search Methods

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

# Returns list[langchain_core.documents.Document]

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

```

### Using Filters and Scores

Supply a dictionary filter for exact-match metadata filtering, or use a callable for custom logic. You can also retrieve similarity scores alongside results.

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

```

## Persisting and Reloading the Index

For production use, persist the index to disk. The `dump` method writes `index.tvim` (binary quantized vectors) and [`docstore.json`](https://github.com/RyanCodrai/turbovec/blob/main/docstore.json) (side-car metadata) through helpers located in [`turbovec-python/python/turbovec/_persist.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/_persist.py).

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

```

Reload later without re-indexing by calling `TurboQuantVectorStore.load` and passing the folder path along with your embeddings model.

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

```

## Using Turbovec as a LangChain Vector Store in Chains and Agents

Because the class implements `as_retriever()`, you can integrate turbovec with LangChain as a vector store retriever in any chain or agent pipeline. The returned retriever respects `search_kwargs` such as `k` and `filter`, so you can control recall without altering chain definitions.

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

```

## Full Working Examples

### Synchronous Example

```python
from turbovec.langchain import TurboQuantVectorStore
from langchain_core.embeddings import OpenAIEmbeddings

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

docs = store.similarity_search("fast vector store", k=2)
for d in docs:
    print(d.page_content, d.metadata)

store.dump("my_store")
reloaded = TurboQuantVectorStore.load("my_store", emb)
print(reloaded.similarity_search("quantization", k=1))

```

### Async Example

```python
import asyncio
from turbovec.langchain import TurboQuantVectorStore
from langchain_core.embeddings import OpenAIEmbeddings

async def demo():
    emb = OpenAIEmbeddings()
    store = await TurboQuantVectorStore.afrom_texts(
        ["async doc 1", "async doc 2"], emb, bit_width=3
    )
    ids = await store.aadd_texts(["more async"], ids=["new-id"])
    results = await store.asimilarity_search("async query", k=3)
    print([r.page_content for r in results])

asyncio.run(demo())

```

### Retriever Chain Example

```python
from langchain_core.prompts import PromptTemplate
from langchain_core.runnables import RunnablePassthrough

retriever = store.as_retriever(search_kwargs={"k": 2})
prompt = PromptTemplate.from_template(
    "Answer the question:\n{question}\nContext:\n{context}"
)
chain = (
    {"question": RunnablePassthrough()}
    | retriever
    | {"context": lambda docs: "\n\n".join(d.page_content for d in docs)}
    | prompt
)

print(chain.invoke({"question": "What does turbovec do?"}))

```

## Summary

- **Install** turbovec with the `langchain` extra to obtain the `TurboQuantVectorStore` class.
- **Construct** the store with any `langchain_core.embeddings.Embeddings` model, choosing a `bit_width` between 2 and 4 and a `similarity` mode of `cosine` or `dot_product`.
- **Ingest** documents via `add_texts`, `from_texts`, or their async equivalents in [`turbovec-python/python/turbovec/langchain.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/langchain.py).
- **Query** using `similarity_search`, `similarity_search_with_score`, or `similarity_search_by_vector`, with optional metadata filters.
- **Persist** the index using `dump`, which writes `index.tvim` and [`docstore.json`](https://github.com/RyanCodrai/turbovec/blob/main/docstore.json), then reload with `load`.
- **Integrate** directly into LangChain chains through the built-in `as_retriever()` method.

## Frequently Asked Questions

### What embedding models work with TurboQuantVectorStore?

Any object that implements the `langchain_core.embeddings.Embeddings` interface works, including `OpenAIEmbeddings`, `HuggingFaceEmbeddings`, or custom stubs. The store calls the embedding model during ingestion and query time to generate vectors.

### How does TurboQuantVectorStore differ from InMemoryVectorStore?

`TurboQuantVectorStore` mirrors the public API of `InMemoryVectorStore` but adds quantized storage, optional persistence, and a Rust-backed `IdMapIndex` for performance. You can swap it in as a drop-in replacement without changing downstream LangChain code because it subclasses the same `VectorStore` base.

### What files are created when persisting a TurboQuantVectorStore?

The `dump` method creates two files in the target folder: `index.tvim`, a binary file containing the quantized vector index, and [`docstore.json`](https://github.com/RyanCodrai/turbovec/blob/main/docstore.json), a JSON side-car storing document texts and metadata. Persistence logic lives in [`turbovec-python/python/turbovec/_persist.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/_persist.py).

### Does TurboQuantVectorStore support metadata filtering?

Yes. The `similarity_search` and `similarity_search_with_score` methods accept a `filter` argument, which can be a dictionary for exact-match metadata filtering or a callable for custom logic. This behavior is fully tested in [`turbovec-python/tests/test_langchain.py`](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/tests/test_langchain.py).