### Install FastPlaid from Source

Source: https://github.com/lightonai/fast-plaid/blob/main/README.md

Install Rust and then install FastPlaid directly from its GitHub repository.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
pip install git+https://github.com/lightonai/fast-plaid.git
```

--------------------------------

### FastPlaid Configuration File Example

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/QUICK_START.md

An example YAML configuration file for FastPlaid, specifying parameters for index path, device, creation, search, and filtering.

```yaml
index_path: "./indexes/my_index"
device: "cuda:0"
low_memory: false

create:
  nbits: 4
  kmeans_niters: 4
  batch_size: 25000

search:
  top_k: 10
  n_ivf_probe: 8
  n_full_scores: 4096
  batch_size: 2000

filtering:
  use_metadata: true
```

--------------------------------

### Windows DLL Loading Failure Example

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/errors.md

This message indicates a failure to load the Torch library on Windows. Ensure Visual C++ redistributables are installed, the path is correct and accessible, and forward slashes are used in paths.

```text
Failed to load Torch library '{path}' via LoadLibraryA. Windows error code: XXX
```

--------------------------------

### FastPlaid Initialization Examples

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/fastplaid-class.md

Demonstrates various ways to initialize the FastPlaid class, including auto-device detection, explicit CPU usage, single GPU, and multi-GPU configurations with different memory settings.

```python
import torch
from fast_plaid import search

# Auto-detect device
fp = search.FastPlaid(index="my_index")

# Explicit CPU (faster init on CPU-only systems)
fp_cpu = search.FastPlaid(index="my_index", device="cpu")

# Single GPU
fp_gpu = search.FastPlaid(index="my_index", device="cuda:0", low_memory=False)

# Multi-GPU with higher VRAM utilization
fp_multi = search.FastPlaid(index="my_index", device=["cuda:0", "cuda:1"], low_memory=False)
```

--------------------------------

### FastKMeans Example Usage

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/kmeans.md

Demonstrates how to instantiate and use the FastKMeans class to train on sample data and obtain centroids. The output centroids will have the shape (k, d).

```python
kmeans = FastKMeans(d=128, k=1024, niter=4, gpu=True)
centroids = kmeans.train(data=samples)  # (1024, 128)
```

--------------------------------

### Install FastPlaid

Source: https://github.com/lightonai/fast-plaid/blob/main/README.md

Install the latest version of FastPlaid using pip.

```bash
pip install fast-plaid
```

--------------------------------

### FastPlaid Quick Start: Create, Search, and Display Results

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/00-START-HERE.md

This snippet shows how to initialize FastPlaid, create an index with documents, perform a search using query embeddings, and print the top results. It requires PyTorch and FastPlaid, and assumes a CUDA-enabled device for initialization.

```python
import torch
from fast_plaid import search

# Initialize
fp = search.FastPlaid(index="my_index", device="cuda")

# Create 100 documents with multi-token embeddings
embeddings = [torch.randn(300, 128) for _ in range(100)]
fp.create(documents_embeddings=embeddings)

# Search with 2 queries
queries = torch.randn(2, 50, 128)
results = fp.search(queries_embeddings=queries, top_k=10)

# Results: list of (document_id, score) pairs per query
for query_idx, result_list in enumerate(results):
    print(f"Query {query_idx}:")
    for doc_id, score in result_list[:3]:
        print(f"  Doc {doc_id}: {score:.2f}")
```

--------------------------------

### Multi-GPU Device Loading Example

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/load-and-storage.md

Demonstrates how to initialize FastPlaid to load separate index copies across multiple GPUs. The search function automatically dispatches queries across these devices.

```python
fp = FastPlaid(index="idx", device=["cuda:0", "cuda:1"])
# Internally:
# indices["cuda:0"] = PyLoadedIndex(device="cuda:0")
# indices["cuda:1"] = PyLoadedIndex(device="cuda:1")

# Search automatically dispatches queries across devices
results = fp.search(queries_embeddings=queries)
```

--------------------------------

### Index Metadata Example

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/types.md

An example JSON structure for the index metadata file, located at {index_path}/metadata.json. It includes details about the number of documents, chunks, embedding dimension, quantization bits, and frozen status.

```json
{
    "num_documents": 1000,
    "num_chunks": 4,
    "embedding_dim": 128,
    "nbits": 4,
    "frozen": false
}
```

--------------------------------

### FastPlaid Setup for CPU-Only Systems

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/configuration.md

Initialize FastPlaid for CPU-only systems by setting `device='cpu'` and `low_memory=True`. Optimize creation and search with smaller batch sizes and appropriate process counts for CPU parallelism.

```python
# Initialization
fp = FastPlaid(index="index", device="cpu", low_memory=True)

# Creation
fp.create(
    documents_embeddings=embeddings,
    nbits=4,  # Balance compression and speed
    kmeans_niters=4,
    batch_size=5000,  # Smaller batch for CPU RAM
)

# Search with CPU parallelism
results = fp.search(
    queries_embeddings=queries,
    batch_size=500,  # Smaller CPU batches
    n_full_scores=1024,  # Fewer candidates
    n_processes=4,  # Use 4 threads/processes
)
```

--------------------------------

### FastPlaid Search Token Scores Example

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/fastplaid-class.md

Provides an example of using the search_token_scores method to retrieve document IDs, aggregate scores, and detailed token similarity matrices. It iterates through the results to print information about each document.

```python
results = fp.search_token_scores(queries_embeddings=torch.randn(1, 50, 128), top_k=3)

for doc_id, score, token_matrix in results[0]:
    print(f"Doc {doc_id}: aggregate score={score:.2f}, token matrix shape={token_matrix.shape}")
    # token_matrix[i, j] = similarity(query_token[i], doc_token[j])
```

--------------------------------

### Install FastPlaid for PyTorch 2.11.0

Source: https://github.com/lightonai/fast-plaid/blob/main/README.md

Install a specific version of FastPlaid compatible with PyTorch 2.11.0.

```bash
pip install fast-plaid==1.4.6.2110
```

--------------------------------

### FastPlaid Quick Start: Indexing and Searching

Source: https://github.com/lightonai/fast-plaid/blob/main/README.md

Initialize FastPlaid, create an index with document embeddings, and perform similarity searches. Supports CPU and GPU devices, with an option for low memory usage on GPU.

```python
import torch

from fast_plaid import search

fast_plaid = search.FastPlaid(index="index", device="cpu", low_memory=True) # or "cuda" for GPU.
# Leave blank for auto-detect, including multi-GPU.
# On CPU, specifying device speeds up initialization.
# On GPU with spare VRAM, pass low_memory=False for significantly faster search but higher VRAM usage. 
# The low_memory flag has no effect when device="cpu" and is set to True by default.

embedding_dim = 128

# Index 100 documents, each with 300 tokens, each token is a 128-dim vector.
fast_plaid.create(
    documents_embeddings=[torch.randn(300, embedding_dim) for _ in range(100)]
)

# Search for 2 queries, each with 50 tokens, each token is a 128-dim vector
scores = fast_plaid.search(
    queries_embeddings=torch.randn(2, 50, embedding_dim),
    top_k=10,
)

print(scores)
```

--------------------------------

### Create FastPlaid Index with Metadata

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/filtering.md

Use this snippet to initialize a FastPlaid index and populate it with document embeddings and associated metadata. Ensure you have the 'torch' and 'datetime' libraries installed.

```python
from fast_plaid import search, filtering
import torch
from datetime import date

metadata = [
    {"doc_id": "a", "length": 500, "date": date(2024, 1, 1)},
    {"doc_id": "b", "length": 300, "date": date(2024, 1, 15)},
    {"doc_id": "c", "length": 1000, "date": date(2024, 2, 1)},
]

fp = search.FastPlaid(index="index")
fp.create(
    documents_embeddings=[torch.randn(100, 128) for _ in range(3)],
    metadata=metadata,
)
```

--------------------------------

### FastPlaid Search Example: Basic Usage

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/fastplaid-class.md

Demonstrates a basic search operation using the search method with random query embeddings. The results are a list of document IDs and their similarity scores.

```python
queries = torch.randn(2, 50, 128)  # 2 queries, 50 tokens, 128-dim

# Basic search
results = fp.search(queries_embeddings=queries, top_k=10)
# [(
#     (20, 1334.55),
#     (91, 1299.57),
#     ...
# )]
```

--------------------------------

### FastPlaid Search Example: With Subset Filter

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/fastplaid-class.md

Shows how to use the search method with a subset filter to restrict the search to a specific list of document IDs. This is useful for targeted searches.

```python
queries = torch.randn(2, 50, 128)  # 2 queries, 50 tokens, 128-dim

# With subset filter
results = fp.search(
    queries_embeddings=queries,
    top_k=5,
    subset=[10, 20, 30, 40, 50]  # search only these 5 docs
)
```

--------------------------------

### NumPy Array Serialization Example

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/load-and-storage.md

Shows how to save and load NumPy arrays, including those containing PyTorch tensors or other Python objects, using `np.save` and `np.load` with `allow_pickle=True`.

```python
# Save
arr = np.array([torch.randn(10, 128), torch.randn(20, 128)], dtype=object)
np.save("buffer.npy", arr)

# Load
arr = np.load("buffer.npy", allow_pickle=True)
tensor_0 = torch.from_numpy(arr[0])
tensor_1 = torch.from_numpy(arr[1])
```

--------------------------------

### FastPlaid Search Example: Per-Query Subset Filter

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/fastplaid-class.md

Illustrates using the search method with a per-query subset filter, allowing different document ID filters for each query. This provides fine-grained control over search scope.

```python
queries = torch.randn(2, 50, 128)  # 2 queries, 50 tokens, 128-dim

# Different subset per query
results = fp.search(
    queries_embeddings=queries,
    top_k=5,
    subset=[[0, 1, 2], [100, 101, 102]]  # query 0 searches docs 0-2, query 1 searches docs 100-102
)
```

--------------------------------

### FastPlaid Cache Coherency Example

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/load-and-storage.md

Demonstrates how FastPlaid handles cache coherency between multiple processes accessing a shared index directory. Process 1 updates the index, and Process 2 automatically detects the change and reloads the index on its next search.

```python
# Process 1
fp1 = FastPlaid(index="shared_idx")
fp1.create(documents_embeddings=embs1)  # mtime updated

# Process 2
fp2 = FastPlaid(index="shared_idx")
fp2.search(...)  # Detects mtime change, reloads automatically
```

--------------------------------

### Catch TorchWithCudaNotFoundError

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/errors.md

Catch the TorchWithCudaNotFoundError if PyTorch is not found in your Python installation. Ensure PyTorch is installed before running FastPlaid.

```python
from fast_plaid.search.fast_plaid import TorchWithCudaNotFoundError

try:
    fp = FastPlaid(index="index")
except TorchWithCudaNotFoundError as e:
    print(f"Torch not found: {e}")
    # Install PyTorch: pip install torch
```

--------------------------------

### Initialize, Create, Update, Filter, and Search with Metadata

Source: https://github.com/lightonai/fast-plaid/blob/main/README.md

Demonstrates the full workflow of initializing FastPlaid, creating and updating documents with metadata, filtering using SQL conditions, and performing a pre-filtered search. Metadata can be accessed for the retrieved documents.

```python
from datetime import date

import torch
from fast_plaid import filtering, search

# 1. Initialize the FastPlaid index
fast_plaid = search.FastPlaid(index="metadata_index")
embedding_dim = 128

# 2. Create initial documents with metadata
initial_embeddings = [torch.randn(10, embedding_dim) for _ in range(3)]
initial_metadata = [
    {"name": "Alice", "category": "A", "join_date": date(2023, 5, 17)},
    {"name": "Bob", "category": "B", "join_date": date(2021, 6, 21)},
    {"name": "Alex", "category": "A", "join_date": date(2023, 8, 1)},
]

fast_plaid.create(documents_embeddings=initial_embeddings, metadata=initial_metadata)

# 3. Update the index with new documents and metadata
new_embeddings = [torch.randn(10, embedding_dim) for _ in range(2)]
new_metadata = [
    {"name": "Charlie", "category": "B", "join_date": date(2020, 3, 15)},
    {
        "name": "Amanda",
        "category": "A",
        "join_date": date(2024, 1, 10),
        "status": "active",
    },
]

fast_plaid.update(documents_embeddings=new_embeddings, metadata=new_metadata)

# 4. Use filtering.where to get the corresponding rows of the FastPlaid index
# which match the SQL condition
subset = filtering.where(
    index="metadata_index",
    condition="name LIKE ? AND join_date > ?",
    parameters=("A%", "2022-12-31"),
)

# 5. Perform a search restricted to the filtered subset
query_embedding = torch.randn(1, 5, embedding_dim)
scores = fast_plaid.search(queries_embeddings=query_embedding, top_k=3, subset=subset)

print("Search results within the subset:")
print(scores)

# 5. Access to the metadata of the retrieved documents
for match in scores:
    print("Metadata of matched documents:")
    print(filtering.get(index="metadata_index", subset=[subset for subset, _ in match]))

```

--------------------------------

### Add FastPlaid to setup.py

Source: https://github.com/lightonai/fast-plaid/blob/main/README.md

Include FastPlaid with a version range in the install_requires list for setup.py.

```python
install_requires=[
    "fast-plaid>=1.4.6.270,<=1.4.6.2110"
]
```

--------------------------------

### FastPlaid Constructor Initialization

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/configuration.md

Initialize FastPlaid with index path and optional device and memory settings. Use `low_memory=False` for faster QPS if index fits in GPU memory.

```python
FastPlaid(
    index: str,
    device: str | list[str] | None = None,
    low_memory: bool = True,
)
```

--------------------------------

### Load and Use FastPlaid with Configuration

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/QUICK_START.md

This Python snippet demonstrates loading FastPlaid configuration from a YAML file and initializing the FastPlaid class with these settings.

```python
import yaml
from fast_plaid import search

with open("config.yaml") as f:
    cfg = yaml.safe_load(f)

fp = search.FastPlaid(
    index=cfg["index_path"],
    device=cfg["device"],
    low_memory=cfg["low_memory"],
)

fp.create(documents_embeddings=embeddings, **cfg["create"])
results = fp.search(queries_embeddings=queries, **cfg["search"])
```

--------------------------------

### Get All Rows from Index

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/filtering.md

Retrieves all rows from a specified index. No additional filtering is applied.

```python
all_rows = filtering.get(index="my_index")
```

--------------------------------

### get

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/filtering.md

Retrieves full row dictionaries, filtered by condition or specific IDs. Supports SQL-like WHERE clauses and subset selection.

```APIDOC
## get

### Description
Retrieves full row dictionaries, filtered by condition or specific IDs.

### Method Signature
```python
def get(
    index: str,
    condition: str | None = None,
    parameters: tuple | list = (),
    subset: list[int] | None = None,
) -> list[dict[str, Any]]
```

### Parameters
#### Path Parameters
- **index** (str) - Required - Path to index directory

#### Query Parameters
- **condition** (str | None) - Optional - SQL WHERE clause with `?` placeholders
- **parameters** (tuple | list) - Optional - Values for `?` placeholders
- **subset** (list[int] | None) - Optional - Specific document IDs to retrieve

### Behavior
- If `subset` provided: returns rows in the order and with duplicates of `subset` list
- If `condition` provided or both `None`: returns rows ordered by `_subset_` ascending
- Raises `ValueError` if both `condition` and `subset` provided

### Returns
`list[dict[str, Any]]` — List of row dictionaries with all columns including `_subset_`

### Example
```python
# Get all rows
all_rows = filtering.get(index="my_index")

# Get rows matching condition
recent = filtering.get(
    index="my_index",
    condition="published > ?",
    parameters=["2024-02-01"],
)

# Get specific rows in specific order (can have duplicates)
rows = filtering.get(index="my_index", subset=[2, 0, 0, 1])
# Returns 4 rows: document 2, 0, 0 again, 1
```
```

--------------------------------

### FastKMeans Class Initialization

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/kmeans.md

Initializes the FastKMeans wrapper with specified parameters. Configure dimensions, number of clusters, iterations, and hardware acceleration.

```python
class FastKMeans:
    def __init__(
        self,
        d: int,
        k: int,
        niter: int = 25,
        gpu: bool = False,
        verbose: bool = False,
        seed: int = 42,
        max_points_per_centroid: int = 256,
        use_triton: bool | None = None,
    )
```

--------------------------------

### Get Rows Matching a Condition

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/filtering.md

Retrieves rows from a specified index that satisfy a given SQL WHERE clause. Use parameters for placeholder values in the condition.

```python
recent = filtering.get(
    index="my_index",
    condition="published > ?",
    parameters=["2024-02-01"],
)
```

--------------------------------

### FastPlaid Class Initialization

Source: https://github.com/lightonai/fast-plaid/blob/main/README.md

Initialize the FastPlaid class with index path and device configuration. Consider low_memory=False for faster queries if VRAM allows.

```python
class FastPlaid:
    def __init__(
        self,
        index: str,
        device: str | list[str] | None = None,
        low_memory: bool = True,
    ) -> None:
```

--------------------------------

### Low Memory Mode Decision Logic

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/load-and-storage.md

This snippet shows how to estimate index size and GPU VRAM to decide whether to use `low_memory=False` for potentially higher QPS. If the index size is less than 80% of available GPU VRAM, pre-loading to the device is considered safe.

```python
# Check index size on disk
import os
index_size_mb = sum(
    os.path.getsize(f) for f in glob.glob("index/*.npy")
) / 1e6

# If < 80% of GPU VRAM, safe to use low_memory=False
gpu_vram_gb = torch.cuda.get_device_properties(0).total_memory / 1e9
if index_size_mb / 1024 < 0.8 * gpu_vram_gb:
    fp = FastPlaid(index="idx", low_memory=False)
```

--------------------------------

### Get Specific Rows by ID

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/filtering.md

Retrieves specific rows from a specified index using a list of document IDs. The order and duplicates in the subset list are preserved in the output.

```python
rows = filtering.get(index="my_index", subset=[2, 0, 0, 1])
# Returns 4 rows: document 2, 0, 0 again, 1
```

--------------------------------

### FastPlaid Initialization for High Throughput

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/configuration.md

Initialize FastPlaid for high throughput (QPS) by setting `low_memory=False` for GPU usage. Index creation and search parameters are optimized for speed.

```python
# Initialization
fp = FastPlaid(index="index", device="cuda:0", low_memory=False)

# Creation (once)
fp.create(
    documents_embeddings=embeddings,
    nbits=4,
    kmeans_niters=4,  # Standard quality
)

# Search
results = fp.search(
    queries_embeddings=queries,
    batch_size=4096,  # Higher for GPU
    n_ivf_probe=8,
    n_full_scores=4096,
    n_processes=1,
)
```

--------------------------------

### Configure Device for Index Loading

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/errors.md

When encountering 'Index could not be loaded on device' errors, consider using the CPU, enabling low memory mode, or reducing the search batch size.

```python
FastPlaid(index="index", device="cpu")
```

```python
FastPlaid(index="index", low_memory=True)
```

```python
fp.search(..., batch_size=1000)
```

--------------------------------

### Create Index Before Searching

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/errors.md

Ensure an index is created before attempting to search it. This prevents 'Index metadata not found' errors.

```python
fp = FastPlaid(index="index")
fp.create(documents_embeddings=embeddings)  # Create first
fp.search(queries_embeddings=queries)       # Then search
```

--------------------------------

### Get Per-Token Similarity Matrices

Source: https://github.com/lightonai/fast-plaid/blob/main/README.md

Use `search_token_scores()` to retrieve the full token-level similarity matrix for each search result. This function accepts the same parameters as `search()` and returns detailed token score information.

```python
results = fast_plaid.search_token_scores(
    queries_embeddings=torch.randn(2, 50, embedding_dim),
    top_k=10,
)

for doc_id, score, token_scores in results[0]:
    print(f"Doc {doc_id}: score={score:.2f}, matrix shape={token_scores.shape}")
    # token_scores.shape == (50, num_doc_tokens)
```

--------------------------------

### Pre-warm GPU for FastPlaid

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/load-and-storage.md

Initialize FastPlaid with the desired device and low_memory=False to load the index onto the GPU during construction. This avoids host-to-device copy overhead on the first search, leading to faster query times.

```python
fp = FastPlaid(index="idx", device="cuda:0", low_memory=False)
# Index loaded to GPU on construction
# First search has no host->device copy overhead
results = fp.search(queries)  # Fast
```

--------------------------------

### Optimize and Revert FastPlaid Index (Freeze/Unfreeze)

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/fastplaid-class.md

Illustrates how to optimize an index for read-only use by freezing it, which reduces disk size. It also shows how to unfreeze the index to allow further updates.

```python
fp.create(documents_embeddings=embeddings)
fp.freeze()  # Reduce disk usage
# fp.update(...)  # Raises RuntimeError

fp.unfreeze()  # Restore ability to mutate
fp.update(documents_embeddings=new_embeddings)
```

--------------------------------

### Provide Metadata During Index Creation

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/errors.md

To avoid 'No metadata database found' errors when using filtering, provide metadata during the index creation or update process.

```python
# Provide metadata during creation
fp.create(documents_embeddings=embeddings, metadata=metadata)
# Then use filtering
ids = filtering.where(index="index", condition="...")
```

--------------------------------

### FastKMeans Class Initialization

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/kmeans.md

Initializes the FastKMeans wrapper with specified parameters for K-means clustering.

```APIDOC
## Class: FastKMeans (Wrapper)

### Description
Initializes the FastKMeans wrapper with specified parameters for K-means clustering.

### Parameters
#### Initialization Parameters
- **d** (int) - Required - Feature dimension
- **k** (int) - Required - Number of clusters
- **niter** (int) - Optional - K-means iterations (default: 25)
- **gpu** (bool) - Optional - Use GPU acceleration (default: False)
- **verbose** (bool) - Optional - Print progress (default: False)
- **seed** (int) - Optional - Random seed (default: 42)
- **max_points_per_centroid** (int) - Optional - Max sampling per centroid (default: 256)
- **use_triton** (bool | None) - Optional - Use Triton optimization (default: None)
```

--------------------------------

### Prevent Invalid Column Names in Metadata

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/errors.md

Ensure metadata keys adhere to SQL column name conventions (start with a letter or underscore, followed by alphanumeric characters or underscores). This prevents ValueErrors when creating or updating filters.

```python
# Bad: contains dash
metadata = [{"user-name": "Alice"}]

# Good: underscores, alphanumeric
metadata = [{"user_name": "Alice"}]
metadata = [{"userName": "Alice"}]
metadata = [{"user123": "Alice"}]
```

--------------------------------

### create

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/filtering.md

Creates a new SQLite database table in the index directory, erasing any existing one. It automatically infers SQL types from Python values.

```APIDOC
## create

### Description
Creates a new SQLite database table in the index directory, erasing any existing one. Automatically infers SQL types from Python values.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **index** (str) - Required - Path to index directory where `metadata.db` will be created
- **metadata** (list[dict[str, Any]]) - Required - List of dictionaries, each representing a document's metadata

### Request Example
```python
from fast_plaid import filtering
from datetime import date

metadata = [
    {"title": "Document A", "category": "news", "published": date(2024, 1, 15), "score": 0.95},
    {"title": "Document B", "category": "blog", "published": date(2024, 2, 20), "score": 0.87},
]

filtering.create(index="my_index", metadata=metadata)
# Output: Database created at 'my_index/metadata.db' with 2 rows.
```

### Response
#### Success Response (200)
None (prints success message)

#### Response Example
Database created at 'my_index/metadata.db' with 2 rows.
```

--------------------------------

### Create a FastPlaid Index

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/QUICK_START.md

Initializes FastPlaid and creates a new index with specified parameters. Ensure PyTorch and CUDA are available if 'cuda' device is chosen.

```python
import torch
from fast_plaid import search

# Initialize
fp = search.FastPlaid(index="my_index", device="cuda")

# Create 100 documents with 300 tokens each, 128-dim embeddings
embeddings = [torch.randn(300, 128) for _ in range(100)]

fp.create(documents_embeddings=embeddings)
```

--------------------------------

### Create and Update FastPlaid Index

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/fastplaid-class.md

Demonstrates the initial creation of an index and subsequent updates. Updates are buffered and trigger centroid expansion when a threshold is met.

```python
fp.create(documents_embeddings=[torch.randn(100, 128) for _ in range(500)])

fp.update(documents_embeddings=[torch.randn(100, 128) for _ in range(50)])

fp.update(documents_embeddings=[torch.randn(100, 128) for _ in range(150)])
```

--------------------------------

### Create Index with Metadata

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/QUICK_START.md

Creates documents and associates metadata with them. Metadata can include various data types like strings and dates.

```python
from datetime import date

metadata = [
    {"title": "Document A", "category": "news", "date": date(2024, 1, 15)},
    {"title": "Document B", "category": "blog", "date": date(2024, 2, 20)},
]

fp.create(documents_embeddings=embeddings, metadata=metadata)
```

--------------------------------

### Safe Index Lifecycle Management with Context Manager

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/errors.md

This pattern ensures that resources for FastPlaid are properly managed, especially during index creation and searching. The `with` statement guarantees that resources are released automatically upon exiting the block, even if errors occur.

```python
try:
    with search.FastPlaid(index="index") as fp:
        fp.create(documents_embeddings=embeddings)
        results = fp.search(queries_embeddings=queries)
finally:
    # Resources automatically released on context exit
    pass
```

--------------------------------

### Optimize Search Speed with low_memory=False

Source: https://github.com/lightonai/fast-plaid/blob/main/README.md

Configure `FastPlaid` with `low_memory=False` to keep index tensors on the GPU for significantly faster queries. This is recommended for high-QPS workloads if the index fits in VRAM. This setting has no effect on CPU.

```python
# Default — low VRAM, slightly slower search
fast_plaid = search.FastPlaid(index="index")

# GPU-resident — higher VRAM, faster queries
fast_plaid = search.FastPlaid(index="index", low_memory=False)
```

--------------------------------

### Load BEIR Dataset

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/evaluation.md

Downloads and loads a specified BEIR benchmark dataset. Use this to obtain documents, queries, relevance judgments, and document IDs for evaluation.

```python
from fast_plaid import evaluation

docs, queries, qrels, doc_ids = evaluation.load_beir("scifact", split="test")

print(f"Documents: {len(docs)}")  # 5183
print(f"Queries: {len(queries)}")  # 300
print(f"Qrels: {len(qrels)}")  # 300

# qrels format:
# {
#     "What is the role of ABO...: {doc_id_1: 1, doc_id_2: 1},
#     "Can mutations in PINK1...": {doc_id_3: 1},
# }

# documents[0] = {"id": "...", "text": "Title Text"}
```

--------------------------------

### FastPlaid Index Creation for Reproducibility

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/configuration.md

Use the `seed` parameter and set `use_triton_kmeans=False` during index creation to ensure byte-identical reproducibility across runs. Triton-based K-means may introduce stochastic behavior.

```python
fp.create(
    documents_embeddings=embeddings,
    seed=42,
    use_triton_kmeans=False,  # Triton has stochastic behavior
    kmeans_niters=4,
)
```

--------------------------------

### FastPlaid Resource Management with Context Manager

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/QUICK_START.md

Use the `with` statement for automatic resource cleanup when working with FastPlaid. This ensures that resources are properly released upon exiting the block, even if errors occur.

```python
with search.FastPlaid(index="idx") as fp:
    fp.create(documents_embeddings=embeddings)
    results = fp.search(queries_embeddings=queries)
# Resources auto-released on exit
```

--------------------------------

### FastPlaid Configuration for Memory Constraints

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/configuration.md

Configure FastPlaid for memory-constrained environments using `device='cpu'` and `low_memory=True`. Employ aggressive compression (`nbits=2`) and small batch sizes for both creation and search.

```python
fp = FastPlaid(index="index", device="cpu", low_memory=True)

# Create with aggressive compression
fp.create(
    documents_embeddings=embeddings,
    nbits=2,  # Extreme compression
    batch_size=1000,  # Small batches
)

# Search with small batch
results = fp.search(
    queries_embeddings=queries,
    batch_size=128,
    n_full_scores=256,  # Few candidates
    n_ivf_probe=2,  # Few clusters
)
```

--------------------------------

### Create Metadata Database

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/filtering.md

Creates a new SQLite database table for metadata within the index directory. Automatically infers SQL types from Python values. Erases any existing table.

```python
from fast_plaid import filtering
from datetime import date

metadata = [
    {"title": "Document A", "category": "news", "published": date(2024, 1, 15), "score": 0.95},
    {"title": "Document B", "category": "blog", "published": date(2024, 2, 20), "score": 0.87},
]

filtering.create(index="my_index", metadata=metadata)
# Output: Database created at 'my_index/metadata.db' with 2 rows.
```

--------------------------------

### Create Multi-Vector Index with FastPlaid

Source: https://github.com/lightonai/fast-plaid/blob/main/README.md

Use the `create` method to build a multi-vector index from document embeddings. Configure K-means clustering, product quantization, and optional metadata for filtering. Ensure reproducible results by setting the `seed` and `use_triton_kmeans` parameters.

```python
def create(
        self,
        documents_embeddings: list[torch.Tensor] | torch.Tensor,
        kmeans_niters: int = 4,
        max_points_per_centroid: int = 256,
        nbits: int = 4,
        n_samples_kmeans: int | None = None,
        batch_size: int = 25_000,
        seed: int = 42,
        use_triton_kmeans: bool | None = None,
        metadata: list[dict[str, Any]] | None = None,
    ) -> "FastPlaid":
```

```python
documents_embeddings: list[torch.Tensor] | torch.Tensor
    A list where each element is a PyTorch tensor representing the multi-vector embedding for a single document.
    Each document's embedding should have a shape of `(num_tokens, embedding_dimension)`. Can also be a single tensor of shape `(num_documents, num_tokens, embedding_dimension)`.
```

```python
kmeans_niters: int = 4 (optional)
    The number of iterations for the K-means algorithm used during index creation.
    This influences the quality of the initial centroid assignments.
```

```python
max_points_per_centroid: int = 256 (optional)
    The maximum number of points (token embeddings) that can be assigned to a single centroid during K-means.
    This helps in balancing the clusters.
```

```python
nbits: int = 4 (optional)
    The number of bits to use for product quantization.
    This parameter controls the compression of your embeddings, impacting both index size and search speed.
    Lower values mean more compression and potentially faster searches but can reduce accuracy.
```

```python
n_samples_kmeans: int | None = None (optional)
    The number of samples to use for K-means clustering.
    If `None`, it defaults to a value based on the number of documents.
    This parameter can be adjusted to balance between speed, memory usage and
    clustering quality. If you have a large dataset, you might want to set this to a
    smaller value to speed up the indexing process and save some memory.
```

```python
batch_size: int = 25_000 (optional)
    Batch size for processing embeddings during index creation.
```

```python
seed: int = 42 (optional)
    Seed for the random number generator used in index creation.
    Setting this ensures reproducible results across multiple runs.
```

```python
use_triton_kmeans: bool | None = None (optional)
    Whether to use the Triton-based K-means implementation.
    If `None`, it will be set to True if the device is not "cpu".
    Triton-based implementation can provide better performance on GPUs.
    Set to False to ensure perfectly reproducible results across runs.
```

```python
metadata: list[dict[str, Any]] | None = None (optional)
    An optional list of metadata dictionaries corresponding to each document being indexed.
    Each dictionary can contain arbitrary key-value pairs that you want to associate with the document.
    If provided, the length of this list must match the number of documents being indexed.
    The metadata will be stored in a SQLite database within the index directory for filtering during searches.
```

--------------------------------

### Add FastPlaid to requirements.txt

Source: https://github.com/lightonai/fast-plaid/blob/main/README.md

Specify a version range for FastPlaid in your requirements.txt file for compatibility.

```text
fast-plaid>=1.4.6.270,<=1.4.6.2110
```

--------------------------------

### FastPlaid Index Creation

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/configuration.md

Create an index using document embeddings and various parameters to control K-means, quantization, and batch processing. Tune `batch_size` for GPU VRAM and consider `use_triton_kmeans=False` for byte-identical reproducibility.

```python
create(
    documents_embeddings: list[torch.Tensor] | torch.Tensor,
    kmeans_niters: int = 4,
    max_points_per_centroid: int = 256,
    nbits: int = 4,
    n_samples_kmeans: int | None = None,
    batch_size: int = 25_000,
    seed: int = 42,
    use_triton_kmeans: bool | None = None,
    metadata: list[dict[str, Any]] | None = None,
    start_from_scratch: int = 1000,
    compress_only: bool = False,
)
```

--------------------------------

### _get_device

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/kmeans.md

Resolves various input types to a torch.device object, handling auto-detection for the best available device.

```APIDOC
## _get_device

### Description
Resolves device specification to `torch.device`. Handles `torch.device` objects, device strings, GPU indices, and auto-detection for the best available device (CUDA > MPS > XPU > CPU).

### Signature
```python
def _get_device(
    preset: str | int | torch.device | None = None
) -> torch.device
```

### Parameters
#### Parameters
- **preset** (`str | int | torch.device | None`) - Required/Optional - Device spec; auto-detect if `None`

### Returns
- **torch.device** - The resolved device object.

### Example
```python
_get_device("cuda:0")       # → torch.device("cuda:0")
_get_device(0)              # → torch.device("cuda:0") if CUDA available
_get_device(None)           # → best available device
```
```

--------------------------------

### load_beir

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/evaluation.md

Downloads and loads a BEIR benchmark dataset from the official repository. It returns documents, queries, relevance judgments, and document IDs.

```APIDOC
## load_beir

### Description
Downloads and loads a BEIR benchmark dataset from the official repository.

### Parameters
#### Path Parameters
- **dataset_name** (str) - Required - BEIR dataset name (e.g., "scifact", "fiqa", "nfcorpus", "arguana", "webis-touche2020", "quora", "scidocs", "trec-covid")
- **split** (str) - Optional - Dataset split to load: "train", "test", "dev" (Default: "test")

### Returns
Tuple of 4 elements:
1. `documents` — List of dicts with keys "id" and "text" (concatenated title + text)
2. `queries` — List of query strings indexed by query ID
3. `qrels` — Dict mapping query string to dict of relevant documents: `{query_str: {doc_id: relevance_score}}`
4. `documents_ids` — Dict mapping document insertion index to original document ID: `{index: doc_id}`

### Example
```python
from fast_plaid import evaluation

docs, queries, qrels, doc_ids = evaluation.load_beir("scifact", split="test")

print(f"Documents: {len(docs)}")
print(f"Queries: {len(queries)}")
print(f"Qrels: {len(qrels)}")
```
```

--------------------------------

### Resolve Device Specification to torch.device

Source: https://github.com/lightonai/fast-plaid/blob/main/_autodocs/api-reference/kmeans.md

Use this function to convert various device specifications (string, int, None) into a torch.device object. It follows a specific resolution order to determine the best available device.

```python
def _get_device(
    preset: str | int | torch.device | None = None
) -> torch.device:
    # ... implementation details ...
    pass

_get_device("cuda:0")       # → torch.device("cuda:0")
_get_device(0)              # → torch.device("cuda:0") if CUDA available
_get_device(None)           # → best available device
```