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

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, mirrors the public surface of langchain_core.vectorstores.InMemoryVectorStore. It delegates indexing to the Rust-backed IdMapIndex in 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.

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.

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, which handles COSINE and DOT_PRODUCT modes along with vector normalization. You can also instantiate directly from a corpus using from_texts:

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.

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 and validated by the test suite in turbovec-python/tests/test_langchain.py.

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

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.

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 (side-car metadata) through helpers located in turbovec-python/python/turbovec/_persist.py.

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.

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.

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

Full Working Examples

Synchronous Example

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

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

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.
• 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, 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, a JSON side-car storing document texts and metadata. Persistence logic lives in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}