> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chonkie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Turbopuffer Handshake

> Export Chonkie's Chunks into a Turbopuffer database.

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.

<Note>
  The Turbopuffer Handshake requires a Turbopuffer API key. You can get one by signing up for a [Turbopuffer account](https://turbopuffer.com).
</Note>

## Installation

Before using the Turbopuffer handshake, make sure to install the required dependencies:

```bash theme={"system"}
pip install chonkie[turbopuffer]
```

## Basic Usage

### Initialization

```python theme={"system"}
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

```python theme={"system"}
from chonkie import TurbopufferHandshake, SemanticChunker

handshake = TurbopufferHandshake(namespace_name="my_documents")

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

handshake.write(chunks)
```

## Parameters

<ParamField path="namespace" type="Optional[tpuf.Namespace]" default="None">
  An existing Turbopuffer Namespace instance to use. If not provided, a new namespace will be created.
</ParamField>

<ParamField path="namespace_name" type="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.
</ParamField>

<ParamField path="embedding_model" type="Union[str, BaseEmbeddings]" default="minishlab/potion-retrieval-32M">
  Embedding model to use. Can be a model name or a BaseEmbeddings instance.
</ParamField>

<ParamField path="api_key" type="Optional[str]" default="None">
  Turbopuffer API key. If not provided, will look for TURBOPUFFER\_API\_KEY environment variable.
</ParamField>

## Authentication

You can authenticate with Turbopuffer in one of two ways:

1. **Environment Variable** (Recommended for development):
   ```bash theme={"system"}
   export TURBOPUFFER_API_KEY='your-api-key-here'
   ```

2. **Directly in code** (Not recommended for production):
   ```python theme={"system"}
   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.