Skip to main content
The TurbopufferHandshake class provides seamless integration between Chonkie’s chunking system and Turbopuffer, a high-performance vector database. Embed and store your Chonkie chunks in Turbopuffer without ever leaving the Chonkie SDK.
The Turbopuffer Handshake requires a Turbopuffer API key. You can get one by signing up for a Turbopuffer account.

​
Installation

Before using the Turbopuffer handshake, make sure to install the required dependencies: 
pip install chonkie[turbopuffer]

​
Basic Usage

​
Initialization

from chonkie import TurbopufferHandshake

# Initialize with default settings (requires TURBOPUFFER_API_KEY environment variable)
handshake = TurbopufferHandshake()

# Or provide an API key directly
handshake = TurbopufferHandshake(api_key="your_turbopuffer_api_key")

# Use a specific namespace
handshake = TurbopufferHandshake(namespace_name="my_documents")

# Or use an existing Turbopuffer namespace
import turbopuffer as tpuf
ns = tpuf.Namespace("existing_namespace")
handshake = TurbopufferHandshake(namespace=ns)

​
Writing Chunks to Turbopuffer

from chonkie import TurbopufferHandshake, SemanticChunker

handshake = TurbopufferHandshake(namespace_name="my_documents")

chunker = SemanticChunker()
chunks = chunker("Chonkie chunks, turbopuffer puffs!")

handshake.write(chunks)

​
Parameters

​
namespace
Optional[tpuf.Namespace]
default:"None"
An existing Turbopuffer Namespace instance to use. If not provided, a new namespace will be created.
​
namespace_name
Union[str, Literal['random']]
default:"random"
Name of the namespace to use. If “random”, a unique name will be generated. Only used if namespace parameter is not provided.
​
embedding_model
Union[str, BaseEmbeddings]
default:"minishlab/potion-retrieval-32M"
Embedding model to use. Can be a model name or a BaseEmbeddings instance.
​
api_key
Optional[str]
default:"None"
Turbopuffer API key. If not provided, will look for TURBOPUFFER_API_KEY environment variable.

​
Authentication

You can authenticate with Turbopuffer in one of two ways:
  1. Environment Variable (Recommended for development): 
    export TURBOPUFFER_API_KEY='your-api-key-here'
  2. Directly in code (Not recommended for production): 
    handshake = TurbopufferHandshake(api_key="your-api-key-here")
For production environments, it’s recommended to use environment variables or a secure secret management system to handle your API keys.
⌘I