How to Integrate Turbovec with LangChain for Vector Storage

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 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.

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, the bit_width parameter controls quantization precision (2–4 bits per dimension), while similarity selects the distance metric.

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 and adds documents simultaneously.

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.

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.

# 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.

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) containing metadata and text. The dump() method in turbovec-python/python/turbovec/_persist.py handles atomic serialization.

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.

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.

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.

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. 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. 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 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.

How does TurboQuantVectorStore handle persistence?

The store serializes quantized vectors to a binary index.tvim file and document metadata to a 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.

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