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

# Types

## StorageConfig

The `StorageConfig` class specifies the backing store for an index's keystores. It is immutable and is built via static factory methods. A single `StorageConfig` is shared across all per-index keystores and is passed to the [`Client`](./client/client) constructor.

CyborgDB supports three backing stores: **memory**, **disk**, and **s3**.

### Factories

```python theme={null}
StorageConfig.memory()
# Ephemeral, no persistence (tests / benchmarking).

StorageConfig.disk(path: str,
                   *,
                   cache_vectors: bool = False,
                   cache_metadata: bool = False,
                   cache_ids: bool = False)
# Local, RocksDB-backed persistent storage.

StorageConfig.s3(bucket: str,
                 *,
                 region: str | None = None,
                 endpoint: str | None = None,
                 prefix: str = "",
                 credentials: S3Credentials | None = None)
# AWS S3 / S3-compatible (MinIO, Ceph, R2, etc.).
```

| Factory           | Description                                                                                                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `memory()`        | Ephemeral in-memory store with no persistence. Use for tests and benchmarking.                                                                                                        |
| `disk(path, ...)` | Local persistent store backed by RocksDB. Optional `cache_*` flags keep vectors / metadata / IDs in memory for faster reads.                                                          |
| `s3(bucket, ...)` | S3 or S3-compatible object store. Set `endpoint` for non-AWS providers (path-style addressing is auto-selected). Omit `credentials` to use the AWS default credential provider chain. |

### Example Usage

```python theme={null}
import cyborgdb_core as cyborgdb

# In-memory (ephemeral)
memory_store = cyborgdb.StorageConfig.memory()

# Local disk (RocksDB-backed), caching vectors in memory
disk_store = cyborgdb.StorageConfig.disk("/tmp/cyborgdb", cache_vectors=True)

# AWS S3 with explicit credentials
s3_store = cyborgdb.StorageConfig.s3(
    "my-bucket",
    region="us-east-1",
    credentials=cyborgdb.S3Credentials(access_key="...", secret_key="..."),
)

# S3-compatible (e.g. MinIO) with default credential chain
minio_store = cyborgdb.StorageConfig.s3(
    "my-bucket",
    endpoint="http://localhost:9000",
)
```

For more info, you can read about supported backing stores [here](../../intro/backing-stores).

***

## S3Credentials

Explicit credentials for the `StorageConfig.s3(...)` factory. Omit `credentials=` on `.s3()` to use the AWS default credential provider chain (environment variables, `~/.aws/credentials`, EC2 instance profile, EKS IRSA).

```python theme={null}
S3Credentials(access_key: str,
              secret_key: str,
              session_token: str | None = None)
```

### Parameters

| Parameter       | Type            | Default | Description                                                     |
| --------------- | --------------- | ------- | --------------------------------------------------------------- |
| `access_key`    | `str`           | -       | S3 access key ID.                                               |
| `secret_key`    | `str`           | -       | S3 secret access key.                                           |
| `session_token` | `str` \| `None` | `None`  | *(Optional)* Temporary session token (for STS / assumed roles). |

### Example Usage

```python theme={null}
import cyborgdb_core as cyborgdb

creds = cyborgdb.S3Credentials(access_key="AKIA...", secret_key="...")
store = cyborgdb.StorageConfig.s3("my-bucket", region="us-east-1", credentials=creds)
```

***

## Storage Precision

`storage_precision` controls the on-disk dtype of the rerank vectors for a DiskIVF index, set at [`create_index`](./client/create-index) time.

| Value                     | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| `numpy.float32` (default) | Full-precision rerank vectors.                             |
| `numpy.float16`           | Halves the on-disk footprint with a slight precision loss. |

The strings `"float32"` and `"float16"` are also accepted.

```python theme={null}
import cyborgdb_core as cyborgdb
import numpy as np

index = client.create_index("my_index", index_key, storage_precision=np.float16)
```

***

## GPUConfig

The `GPUConfig` class configures which operations should use GPU acceleration. GPU acceleration requires CUDA support.

### Parameters

| Parameter | Type   | Default | Description                                     |
| --------- | ------ | ------- | ----------------------------------------------- |
| `upsert`  | `bool` | `False` | *(Optional)* Enable GPU for upsert operations   |
| `train`   | `bool` | `False` | *(Optional)* Enable GPU for training operations |

### Properties (Read-Only)

| Property | Type   | Description                                    |
| -------- | ------ | ---------------------------------------------- |
| `upsert` | `bool` | Whether GPU is enabled for upsert operations   |
| `train`  | `bool` | Whether GPU is enabled for training operations |
| `query`  | `bool` | Whether GPU is enabled for query operations    |
| `all`    | `bool` | Whether all GPU operations are enabled         |
| `none`   | `bool` | Whether no GPU operations are enabled          |

### Example Usage

```python theme={null}
import cyborgdb_core as cyborgdb

# Enable GPU for upsert and training
gpu_config1 = cyborgdb.GPUConfig(upsert=True, train=True)

# Enable GPU only for training
gpu_config2 = cyborgdb.GPUConfig(train=True)

# Disable GPU (default)
gpu_config3 = cyborgdb.GPUConfig()

# Check GPU configuration
if gpu_config1.all:
    print("All GPU operations enabled")

if gpu_config2.train:
    print("GPU enabled for training")
```

***

## DistanceMetric

`DistanceMetric` is a string representing the distance metric used for the index. Options include:

* `"cosine"`: Cosine similarity.
* `"euclidean"`: Euclidean distance.
* `"squared_euclidean"`: Squared Euclidean distance.

***

## KMSBlob

`KMSBlob` describes a per-index envelope recording how the index KEK is wrapped by an external KMS. It is used with the module-level KMS functions (`create_index_kms`, `push_index_kms`, `get_index_kms`, `delete_index_kms`). This is an advanced, optional surface primarily for the service layer; embedded SDK users supplying their own KEK can ignore it or use `provider="none"`.

```python theme={null}
KMSBlob(kms_name: str = "",
        provider: str = "",
        key_id: str = "",
        region: str = "",
        wrapped_kek: bytes = b"",
        version: int = 1,
        created_at: int = 0)
```

### Fields

| Field         | Type    | Description                                      |
| ------------- | ------- | ------------------------------------------------ |
| `kms_name`    | `str`   | Human-readable name of the KMS configuration.    |
| `provider`    | `str`   | KMS provider: `"aws"`, `"aws-kms"`, or `"none"`. |
| `key_id`      | `str`   | Identifier of the wrapping key within the KMS.   |
| `region`      | `str`   | Region of the KMS / key.                         |
| `wrapped_kek` | `bytes` | The wrapped index KEK.                           |
| `version`     | `int`   | Envelope version.                                |
| `created_at`  | `int`   | Creation timestamp (unix epoch seconds).         |

### Example Usage

```python theme={null}
import cyborgdb_core as cyborgdb

blob = cyborgdb.KMSBlob(
    kms_name="prod",
    provider="aws-kms",
    key_id="arn:aws:kms:us-east-1:111122223333:key/abcd",
    region="us-east-1",
    wrapped_kek=wrapped_bytes,
)
```